Initial GeoIntel V1 foundation

2026-06-16 23:36:32 +02:00
commit 6ea3586a3e
605 changed files with 45284 additions and 0 deletions
@@ -0,0 +1,134 @@
+# 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.