# Repository Conventions

## Canonical structure

```text
GeoIntel/
  backend/
    app/
      api/
        routes/
        deps.py
      core/
        config.py
        errors.py
        logging.py
      db/
        session.py
        base.py
        migrations/
      models/
      schemas/
      services/
      repositories/
      workers/
      providers/
      utils/
    tests/
    pyproject.toml
    README.md

  frontend/
    src/
      app/
      pages/
      components/
      features/
      hooks/
      lib/
      services/
      stores/
      types/
      styles/
    package.json
    README.md

  docs/
  datasets/
    raw/
    processed/
    cache/
  storage/
    uploads/
    tiles/
    masks/
    reports/
  exports/
  models/
  scripts/
  tests/
    fixtures/
```

## Backend naming
- SQLAlchemy models: singular class names, e.g. `Project`, `Dataset`, `AnalysisRun`.
- Pydantic schemas: `ProjectCreate`, `ProjectRead`, `DatasetRead`.
- Services: `ProjectService`, `RasterService`.
- Repositories: `ProjectRepository`.
- Route files: plural noun, e.g. `projects.py`, `datasets.py`, `analysis_runs.py`.

## Frontend naming
- Pages end with `Page`, e.g. `DatasetManagerPage.tsx`.
- Components are PascalCase.
- Hooks start with `use`, e.g. `useProjects.ts`.
- API clients live under `src/services/api`.
- Domain types live under `src/types`.
- Feature-specific components live under `src/features/<feature>`.

## Documentation rule
When Codex implements or changes a module, it must update at least one of:
- docs/TODO.md
- docs/IMPLEMENTATION_BACKLOG.md
- docs/CODEX_EXECUTION_LOG.md
- relevant technical spec if a documented decision changes

## No generated noise
Do not commit:
- node_modules
- .venv
- __pycache__
- large raw datasets
- model weights unless explicitly requested
- generated tiles/masks/reports except small fixtures

## Environment variables
All configurable external sources must use environment variables:
- DATABASE_URL
- REDIS_URL
- STORAGE_ROOT
- GRB_WFS_URL
- OSM_OVERPASS_URL
- OPENAI_API_KEY optional later
- MODEL_STORAGE_ROOT

## Testing conventions
Backend:
- pytest
- fixture datasets under tests/fixtures
- geometry tests must use small artificial polygons

Frontend:
- typecheck must pass
- lint must pass if configured
- components must handle loading/error/empty states

## Build conventions
Every build pass should report:
- files changed
- modules completed
- tests run
- known limitations
- next recommended pass

## Geospatial correctness conventions
- Never compute area/length in EPSG:4326.
- Always store CRS metadata.
- Always warn on missing CRS.
- Never export geospatial outputs from non-georeferenced rasters unless the output is explicitly marked image-space only.

## Mocking rule
Mock providers are allowed only when:
- they are named `Development...Provider` or `Fixture...Provider`;
- they are clearly isolated;
- UI labels say development/demo provider;
- real provider interfaces are already defined.