geointel/docs/REPOSITORY_CONVENTIONS.md

Repository Conventions

Canonical structure

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.