# Project structure

Backend and frontend are split; **all backend and Boundary Commission code lives under `backend/`**. Root Python files are re-exports only.

## Backend (canonical – use this)

- **Entry point:** `backend.app.main:app`. Run with `./START_API.sh` or `PYTHONPATH=. uvicorn backend.app.main:app --host 0.0.0.0 --port 8001`.
- **Package:** `backend/`
  - **`backend/app/main.py`** – FastAPI app: CORS, lifespan, auth router, **Boundary Commission router**, and all endpoints (documents, dictionary, schema, properties, GIS, cashier, etc.).
  - **`backend/app/config.py`** – Env-based config (DB, auth, paths).
  - **`backend/auth/`** – Auth: access + refresh tokens, rate limiting, login/refresh/me/logout.
  - **`backend/services/`** – `browser_service.py`, `boundary_document_service.py`.
  - **`backend/api/`** – **Boundary Commission:** `boundary_models.py`, `boundary.py` (router for `/boundary/*`: boundaries, disputes, documents/upload, PDF, list).
  - **`backend/aumentum_api.py`** – Re-exports `app` from `backend.app.main` (alternative entry: `uvicorn backend.aumentum_api:app`).
  - **`backend/aumentum_browser_service.py`** – Re-exports from `backend.services.browser_service` (for scripts importing this name).

## Root stubs (re-export from backend – do not add logic)

- **`aumentum_api.py`** – Stub: `from backend.aumentum_api import app`. So `uvicorn aumentum_api:app` works with `PYTHONPATH=.`.
- **`aumentum_browser_service.py`** – Stub: re-exports from `backend.aumentum_browser_service`. Scripts need `PYTHONPATH=.`.
- **`boundary_document_service.py`** – Re-exports from `backend.services.boundary_document_service`.
- **Removed:** `boundary_commission_api.py` and `boundary_commission_models.py` (canonical: `backend/api/`).

## Frontend

- **App:** `plagis-nextjs/` (Next.js).
- **Start:** From project root, `cd plagis-nextjs && npm run dev` (or use `plagis-nextjs/start_dev.sh`).
- **API base URL:** Resolved at runtime (e.g. `/api` when behind nginx, or `NEXT_PUBLIC_API_URL`).

## Running

1. **Backend:** From project root, `./START_API.sh` (uses `backend.app.main:app`).
2. **Frontend:** `cd plagis-nextjs && npm run dev`.
3. **Env:** Copy `.env.example` to `.env`; set `AUTH_SECRET_KEY`, DB vars, and `CONTENTSTORE_BASE`.

## Scripts and tools

- **`scripts/`** – Admin scripts (`create_admin_user.py`, `create_roles.py`, `assign_role_to_user.py`, `check_document.py`), shell scripts (restart API, deploy, mount, etc.), and **`scripts/sql/`** for SQL files. Run Python scripts from project root: **`PYTHONPATH=. python scripts/create_admin_user.py`**.
- **`docs/`** – All documentation (including `PROJECT_STRUCTURE.md`, `CLEANUP.md`), database schema reference files, and misc notes.