qlockify-frontend-deployment/README.md

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

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

npm install

2. Configure environment

Copy and fill:

.env.sample -> .env

Default local API base:

VITE_API_BASE_URL=http://localhost:8000

If your backend runs behind /api, use:

VITE_API_BASE_URL=http://localhost:8000/api

3. Start development server

npm run dev

Default local URL:

• http://localhost:5173

Available Scripts

Development:

npm run dev

Production build:

npm run build

Preview production build:

npm run preview

Lint:

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