103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# Guilan ACE Backend
|
|
|
|
## Stack
|
|
- Django 5 with Ninja API routers
|
|
- PostgreSQL, Redis, Celery, Gunicorn
|
|
- Prometheus instrumentation through `django-prometheus`
|
|
|
|
## Layout
|
|
```text
|
|
guilan-ace-backend/
|
|
apps/
|
|
users/
|
|
blog/
|
|
gallery/
|
|
events/
|
|
communications/
|
|
payments/
|
|
certificates/
|
|
core/
|
|
config/
|
|
static/
|
|
templates/
|
|
manage.py
|
|
```
|
|
|
|
## Local development on Windows (no Compose)
|
|
|
|
The backend, frontend, Celery worker, and Celery beat run as separate processes. PostgreSQL must listen on `127.0.0.1:5432` and Redis on `127.0.0.1:6379`. Redis can be a standalone container with its port published; no other service needs Docker.
|
|
|
|
Use Python 3.13 for the pinned dependencies. From this directory in PowerShell:
|
|
|
|
```powershell
|
|
py -3.13 -m venv .venv
|
|
python -m pip install -r requirements.txt
|
|
Copy-Item .env.development.example .env
|
|
```
|
|
|
|
Fill in `SECRET_KEY`, `JWT_SECRET_KEY`, `DB_PASSWORD`, `SMS_APIKEY`, the SMS template IDs you use, and `ZARINPAL_MERCHANT_ID` in the ignored `.env`. Leave `ZARINPAL_USE_SANDBOX=True`. The frontend's `.env` should contain `NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000` and `NEXT_PUBLIC_SITE_URL=http://localhost:8080`. Copy its `.env.sample` if needed.
|
|
|
|
Create the local database once, then apply migrations. Use the PostgreSQL `createdb.exe` from your installation if it is not on `PATH`:
|
|
|
|
```powershell
|
|
$env:PGPASSWORD = '<your local PostgreSQL password>'
|
|
createdb -h 127.0.0.1 -p 5432 -U postgres guilan_ace_local
|
|
python manage.py migrate
|
|
```
|
|
|
|
Open four PowerShell terminals. Run the first three in this backend directory:
|
|
|
|
```powershell
|
|
python manage.py runserver 127.0.0.1:8000
|
|
```
|
|
|
|
```powershell
|
|
celery -A config.services.celery worker --pool=solo --loglevel=INFO
|
|
```
|
|
|
|
```powershell
|
|
New-Item -ItemType Directory -Force (Join-Path $env:TEMP 'guilan-ace-local') | Out-Null
|
|
celery -A config.services.celery beat --loglevel=INFO --schedule (Join-Path $env:TEMP 'guilan-ace-local\celerybeat-schedule')
|
|
```
|
|
|
|
Run the frontend in the sibling `guilan-ace-frontend` directory:
|
|
|
|
```powershell
|
|
npm.cmd ci
|
|
npm.cmd run dev
|
|
```
|
|
|
|
Open `http://localhost:8080` for the site and `http://127.0.0.1:8000/api/docs` for the API. Django serves local media under `/media/`. The first Next.js page request may take a while to compile.
|
|
|
|
The June 12, 2026 server backup was restored locally into `guilan_ace_local` and this repository's ignored `media/` directory. The backup also supplied the local SMS.ir OTP credentials. Its other SMS template IDs were empty. The local `.env` points at localhost and Zarinpal's sandbox; never replace it directly with the backup's production environment file. The previous local `.env` is saved as ignored `.env.bak`.
|
|
|
|
## Tests
|
|
|
|
Install test dependencies, then run the two pytest suites:
|
|
|
|
```powershell
|
|
python -m pip install -r requirements-test.txt
|
|
python -m pytest -m unit
|
|
python -m pytest -m integration
|
|
```
|
|
|
|
CI uses PostgreSQL for integration tests and combines branch coverage from both suites. The same coverage gate can be run locally after configuring the test database:
|
|
|
|
```powershell
|
|
python -m coverage run -m pytest -m unit
|
|
python -m coverage run --append -m pytest -m integration
|
|
python -m coverage json -o coverage.json
|
|
python scripts/check_coverage.py coverage.json --minimum 80
|
|
```
|
|
|
|
Coverage includes executable modules in `apps`, `core`, and `config`. The fixed exclusions are migrations, tests, `__init__.py`, `apps.py`, `config/settings`, ASGI/WSGI entrypoints, and constant-only service config modules (`location`, `notifications`, and `zarinpal`). Every included module must reach 80% combined statement and branch coverage.
|
|
|
|
## Notes
|
|
- Domain routers live under `apps/<domain>/api`.
|
|
- Shared auth helpers live in `core/authentication.py`.
|
|
- Shared base models, admin helpers, choices, and template tags live under `core/`.
|
|
|
|
## Project-local skills
|
|
|
|
Backend implementation guidance is vendored in `.agents/skills/`: `api-and-interface-design`, `deprecation-and-migration`, and `test-driven-development`. Shared team guidance is also included: `grill-me`, `grilling`, `planning-and-task-breakdown`, `documentation-and-adrs`, and `git-workflow-and-versioning`. These directories are part of this repository so they are available after cloning it.
|