173 lines
2.8 KiB
Markdown
173 lines
2.8 KiB
Markdown
# Qlockify Frontend
|
|
|
|
Frontend web application for Qlockify.
|
|
|
|
## Repository
|
|
|
|
- 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`
|
|
|
|
## What This Repo Contains
|
|
|
|
- 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
|
|
|
|
## Stack
|
|
|
|
- React `19`
|
|
- TypeScript
|
|
- Vite
|
|
- React Router
|
|
- Tailwind CSS
|
|
- Headless UI / custom UI primitives
|
|
- Sonner toasts
|
|
- Recharts
|
|
|
|
## Project Layout
|
|
|
|
```text
|
|
qlockify-frontend/
|
|
public/
|
|
src/
|
|
api/
|
|
components/
|
|
context/
|
|
hooks/
|
|
lib/
|
|
locales/
|
|
pages/
|
|
index.html
|
|
package.json
|
|
```
|
|
|
|
## Main Areas
|
|
|
|
- `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
|
|
|
|
## 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
|