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

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

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:

.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

.venv\Scripts\python.exe manage.py migrate

4. Start the API

.venv\Scripts\python.exe manage.py runserver

Default local URL:

http://localhost:8000

Useful Commands

Run all tests:

.venv\Scripts\python.exe manage.py test --settings=config.settings.test

Run coverage:

.venv\Scripts\python.exe -m coverage run manage.py test --settings=config.settings.test
.venv\Scripts\python.exe -m coverage report

Run Ruff:

.venv\Scripts\python.exe -m ruff check .

Run Black:

.venv\Scripts\python.exe -m black .

Start Celery worker:

celery -A config worker -l INFO

Start Celery beat:

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