geointel/docs/40-build-launch/BUILD_SUCCESS_DEFINITION.md

BUILD SUCCESS DEFINITION — Sprint 1 / First Codex Run

This document defines the exact point at which Codex must stop expanding scope and consider the first implementation run successful.

Purpose

The first build is not successful because many features exist. It is successful when the foundation is stable, testable and ready for the next module.

Sprint 1 success statement

Sprint 1 is successful when GeoIntel can run locally with a backend, frontend, database and a minimal geospatial dataset workflow.

The vertical slice is:

Project
  -> Area
  -> Dataset upload/registration
  -> Metadata extraction
  -> PostGIS persistence
  -> Minimal map display
  -> GeoJSON export

Required backend success criteria

• FastAPI application starts without import errors.
• /health returns a successful response.
• /docs or OpenAPI schema is available in development.
• Database configuration is loaded from environment variables.
• PostgreSQL connection is verified by a health or readiness check.
• PostGIS extension is created or verified by migration/bootstrap logic.
• Project CRUD works through API endpoints.
• Area CRUD works with valid GeoJSON polygon input.
• Dataset registration or upload works for at least GeoJSON.
• Dataset metadata is extracted and persisted.
• API responses use the canonical response envelope.
• Errors use the canonical error format.

Required database success criteria

• Alembic or equivalent migration path exists.
• Core tables exist:
  • projects
  • areas
  • datasets
  • dataset_versions or documented equivalent
  • analysis_runs placeholder/table if needed for future compatibility
  • exports placeholder/table if needed for future compatibility
• Geometry columns use PostGIS types.
• CRS/SRID rules follow docs/specs/GIS_STANDARDS.md.
• Demo seed data can be loaded or fixtures can be used in tests.

Required frontend success criteria

• React/Vite application starts.
• Main layout is visible.
• MapLibre map renders.
• Project list/detail state exists.
• Dataset upload/registration UI exists for the Sprint 1 dataset type.
• Area display or drawing/import flow exists in minimal form.
• API client uses configured backend base URL.
• Loading, empty and error states exist for the implemented pages.

Required storage success criteria

• Uploaded/registered dataset files are stored under a controlled storage path.
• Storage paths are not hardcoded to a developer machine.
• Metadata in the database references stored files where applicable.
• Generated exports go to a controlled exports folder.

Required testing success criteria

At minimum:

• Backend import smoke test passes.
• Health endpoint test passes.
• Database connection/migration smoke test passes or has a documented fallback if no DB is available in CI.
• GeoJSON fixture validation passes.
• Frontend build or typecheck passes.
• make readiness passes.

Explicitly not required for Sprint 1

Do not block Sprint 1 on:

• YOLO inference.
• SAM inference.
• Sentinel download automation.
• GRB live WFS integration.
• LiDAR processing.
• Training Studio.
• AI Copilot.
• Advanced reporting.
• Multi-user authentication.
• Production deployment.

Stop condition

When all Sprint 1 success criteria are met, Codex must stop feature expansion and produce:

• changelog entry;
• commands run;
• test results;
• known limitations;
• next pass recommendation.