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.

2.9 KiB Raw Blame History