first commit

backend/README.md

@@ -0,0 +1,67 @@
+# Desi Clans — Backend
+
+FastAPI application with layered architecture, PostgreSQL, SQLAlchemy, Alembic, and JWT-ready configuration.
+
+## Layout
+
+```
+app/
+├── main.py              # Application factory
+├── core/                # Settings, dependencies, errors
+├── db/                  # SQLAlchemy engine, session, Base
+├── models/              # ORM entities & enums
+├── schemas/             # Pydantic request/response models
+├── api/                 # API routers
+│   └── routes/          # Route modules (health, …)
+├── services/            # Business logic
+└── utils/               # Storage and helpers
+```
+
+Legacy route modules under `app/routers/` remain for a future mount phase.
+
+## Prerequisites
+
+- Python 3.11+
+- PostgreSQL 15+ (local or Docker)
+
+## Setup
+
+```bash
+cd backend
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Start Postgres (from repo root):
+
+```bash
+docker compose up -d db
+```
+
+Run migrations and optional seed:
+
+```bash
+python scripts/migrate.py
+python scripts/seed_catalog.py
+python scripts/seed.py
+```
+
+Start API:
+
+```bash
+uvicorn app.main:app --reload --port 8000
+```
+
+Health (includes DB check): [http://localhost:8000/api/health](http://localhost:8000/api/health)
+
+## Tests
+
+```bash
+pytest tests/
+```
+
+## Environment
+
+Copy `.env.example` to `.env`. Required: `DATABASE_URL`, `SECRET_KEY`.