# 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