Jens
faeb58ef6d
GeoIntel release gates / Compile, test, contracts and builds (push) Successful in 1m49s
GeoIntel release gates / Python and npm vulnerability policy (push) Successful in 21s
GeoIntel release gates / Production AI image, SBOM and container scan (push) Successful in 5m39s
GeoIntel release gates / Deploy exact gated revision to Unraid (push) Failing after 58m43s
135 lines
2.9 KiB
Markdown
135 lines
2.9 KiB
Markdown
# 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.
|