From 9b1cd772fb8bdcdfcf37f772dd02f3d03f320b9b Mon Sep 17 00:00:00 2001
From: Amirhossein Khalili <amirhosseinkhalili901@gmail.com>
Date: Fri, 1 May 2026 10:47:47 +0330
Subject: [PATCH] chore(readme): add README.md

---
 README.md | 217 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 158 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index d2e7761..c0d4b29 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,172 @@
-# React + TypeScript + Vite
+# Qlockify Frontend
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Frontend web application for Qlockify.
 
-Currently, two official plugins are available:
+## Repository
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- Main deployment entrypoint: `https://git.amiirkhl.ir/Qlockify/qlockify-core-deployment.git`
+- Frontend repository declared by `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-frontend-deployment.git`
+- Backend repository declared by `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-backend-deployment.git`
 
-## React Compiler
+## What This Repo Contains
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+- React application
+- authenticated product UI
+- public landing page
+- workspace-based business screens
+- Persian and English localization
+- Google sign-in onboarding UI
+- client-side caching and API integration layer
 
-## Expanding the ESLint configuration
+## Stack
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+- React `19`
+- TypeScript
+- Vite
+- React Router
+- Tailwind CSS
+- Headless UI / custom UI primitives
+- Sonner toasts
+- Recharts
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+## Project Layout
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```text
+qlockify-frontend/
+  public/
+  src/
+    api/
+    components/
+    context/
+    hooks/
+    lib/
+    locales/
+    pages/
+  index.html
+  package.json
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+## Main Areas
 
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+- `src/pages`: route-level screens
+- `src/components`: reusable UI and page modules
+- `src/api`: backend request layer
+- `src/context`: workspace and notification state
+- `src/locales`: English and Persian dictionaries
+- `src/lib`: session, permissions, caching, helpers
 
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+## Local Development
+
+### 1. Install dependencies
+
+```powershell
+npm install
 ```
+
+### 2. Configure environment
+
+Copy and fill:
+
+```text
+.env.sample -> .env
+```
+
+Default local API base:
+
+```text
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+If your backend runs behind `/api`, use:
+
+```text
+VITE_API_BASE_URL=http://localhost:8000/api
+```
+
+### 3. Start development server
+
+```powershell
+npm run dev
+```
+
+Default local URL:
+
+- `http://localhost:5173`
+
+## Available Scripts
+
+Development:
+
+```powershell
+npm run dev
+```
+
+Production build:
+
+```powershell
+npm run build
+```
+
+Preview production build:
+
+```powershell
+npm run preview
+```
+
+Lint:
+
+```powershell
+npm run lint
+```
+
+## Product Routes
+
+Main application routes include:
+
+- `/`
+- `/auth`
+- `/auth/google/callback`
+- `/timesheet`
+- `/reports`
+- `/logs`
+- `/notifications`
+- `/workspaces`
+- `/projects`
+- `/clients`
+- `/tags`
+- `/profile`
+
+## Authentication UX
+
+Supported flows in the UI:
+
+- password login
+- OTP login
+- OTP registration
+- Google sign-in
+
+Google sign-in flow:
+
+- start from the auth page
+- backend performs OAuth callback handling
+- frontend callback page loads the flow state
+- new users complete mobile onboarding
+- existing mobile owners verify claim via OTP
+
+## Localization
+
+The application is bilingual:
+
+- English
+- Persian
+
+Translation dictionaries live in:
+
+- `src/locales/en.ts`
+- `src/locales/fa.ts`
+
+## Notes
+
+- the frontend expects the backend API contract defined in the backend repo
+- deployment, domain, SSL, and Nginx details belong in the deployment repo
+- this repo focuses on application UI and browser runtime behavior