194 lines
3.8 KiB
Markdown
194 lines
3.8 KiB
Markdown
# 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
|