diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7026bd2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,193 @@
+# Qlockify Backend
+
+Backend API and background job layer 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
+
+- Django 5 API
+- DRF-based authentication and business APIs
+- JWT auth
+- Redis-backed caching
+- Celery tasks
+- audit/logging infrastructure
+- report generation and exports
+- Google sign-in backend flow
+
+## Stack
+
+- Python `3.14`
+- Django `5.2`
+- Django REST Framework
+- PostgreSQL
+- Redis
+- Celery
+- Simple JWT
+- drf-spectacular
+- django-auditlog
+
+## Project Layout
+
+```text
+qlockify-backend/
+  apps/
+    users/
+    workspaces/
+    clients/
+    projects/
+    tags/
+    time_entries/
+    reports/
+    notifications/
+    logs/
+  config/
+    settings/
+    services/
+  core/
+  requirements/
+  manage.py
+```
+
+## Main Domains
+
+- `users`: auth, OTP, profile, Google OAuth link flow
+- `workspaces`: workspace membership, permissions, rates
+- `clients`: client CRUD
+- `projects`: project CRUD
+- `tags`: tag CRUD
+- `time_entries`: timer and timesheet data
+- `reports`: chart/table/day-details/export
+- `notifications`: in-app notifications and SSE stream
+- `logs`: workspace activity logs
+
+## Local Development
+
+### 1. Create environment
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -r requirements\base.txt
+pip install -r requirements\dev.txt
+```
+
+### 2. Configure environment variables
+
+Copy and fill:
+
+```text
+.env.sample -> .env
+```
+
+At minimum configure:
+
+- `DJANGO_SECRET_KEY`
+- `POSTGRES_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `REDIS_HOST`
+- `REDIS_PORT`
+
+### 3. Run migrations
+
+```powershell
+.venv\Scripts\python.exe manage.py migrate
+```
+
+### 4. Start the API
+
+```powershell
+.venv\Scripts\python.exe manage.py runserver
+```
+
+Default local URL:
+
+- `http://localhost:8000`
+
+## Useful Commands
+
+Run all tests:
+
+```powershell
+.venv\Scripts\python.exe manage.py test --settings=config.settings.test
+```
+
+Run coverage:
+
+```powershell
+.venv\Scripts\python.exe -m coverage run manage.py test --settings=config.settings.test
+.venv\Scripts\python.exe -m coverage report
+```
+
+Run Ruff:
+
+```powershell
+.venv\Scripts\python.exe -m ruff check .
+```
+
+Run Black:
+
+```powershell
+.venv\Scripts\python.exe -m black .
+```
+
+Start Celery worker:
+
+```powershell
+celery -A config worker -l INFO
+```
+
+Start Celery beat:
+
+```powershell
+celery -A config beat -l INFO
+```
+
+## Authentication
+
+Supported auth flows:
+
+- password login
+- OTP send + OTP login
+- password reset via OTP
+- Google sign-in with backend callback
+
+Google sign-in is mobile-first:
+
+- Google proves email ownership
+- first-time Google users must enter a mobile number
+- if that mobile already belongs to an existing account, OTP verification is required before linking Google
+- email matches alone do not auto-link accounts
+
+Required Google env vars:
+
+- `GOOGLE_OAUTH_CLIENT_ID`
+- `GOOGLE_OAUTH_CLIENT_SECRET`
+- `GOOGLE_OAUTH_REDIRECT_URI`
+- `GOOGLE_OAUTH_FRONTEND_CALLBACK_URL`
+
+## Caching and Async Work
+
+- Redis is used for cache, OTP state, and Celery broker/result backend
+- query-heavy report endpoints use targeted server-side caching
+- workspace-scoped reference data uses targeted caching with namespace invalidation
+- Celery handles async jobs such as SMS and report export generation
+
+## API Documentation
+
+The project exposes OpenAPI/Swagger via DRF Spectacular in deployment.
+
+Production docs access is handled by Nginx in the deployment repo.
+
+## Notes
+
+- `.env` is intentionally not committed
+- deployment-specific setup belongs in the deployment repository, not here
+- domain, SSL, Nginx, Docker Compose, and host-level operations are documented in the deployment repo