geointel/docs/DEVELOPMENT_RULES.md

GeoIntel Kempen — Development Rules v1.0

These rules apply to Codex and every AI/developer working in this repository.

Product rules

1. GeoIntel is a GeoAI Workbench, not a generic dashboard.
2. Analysis and geospatial outputs are the product. Maps support the analysis.
3. The main technical story is: data → processing → AI/model → GIS output → QA/QC → export.
4. GRB/official reference data and QA/QC are core differentiators.

Implementation rules

1. Backend-first for data models, processing contracts and APIs.
2. UI must be API-driven; do not hardcode fake results.
3. Mock data is allowed only for explicit UI skeletons and must be clearly marked.
4. No placeholder endpoints that return success without doing useful work.
5. Every long-running operation must be modeled as a job/analysis run.
6. Every dataset must have metadata.
7. Every derived output must reference source datasets and analysis run.
8. Every export must be traceable.
9. Every geometry operation must handle CRS and invalid geometries.
10. Every metric must include unit and calculation method.

Code quality rules

1. Type-safe code where possible.
2. Separate API routes, services, database models, schemas and processing utilities.
3. Avoid giant files.
4. Use explicit names: RasterMetadataService, DetectionPipeline, QaqcService.
5. Add tests for pure processing functions.
6. Do not silently swallow errors.
7. Return actionable validation messages.

GIS rules

1. Never calculate area/length in geographic degrees.
2. Reproject to a metric CRS for calculations.
3. Store original CRS metadata.
4. Repair invalid geometries before analysis, but record that repair happened.
5. Keep raw attributes in attributes_json when normalizing external features.

AI rules

1. AI detections must be stored as geospatial features.
2. Model outputs must record model name, version, classes and confidence threshold.
3. Do not fake model results.
4. If a model is unavailable, show a clear system readiness message.
5. The AI copilot is optional and must only interpret real metrics.

Frontend rules

1. Every page needs useful empty states.
2. Every analysis result needs an export action.
3. Every map layer needs visibility, opacity and inspect controls.
4. Every job needs visible status.
5. Avoid clutter; use workbench panels.

Delivery rules

Every build response should include:

• What changed.
• What files changed.
• How to run/test.
• What remains open.
• Any risks or assumptions.

Do not hide unfinished core functionality behind a TODO list unless explicitly requested.