geointel/docs/17-max-prep/M9_BUILD_BLOCKERS_AND_RECOVERY.md

M9 Build Blockers and Recovery

Database connection failure

Symptoms:

• backend cannot connect to PostgreSQL,
• migrations fail,
• PostGIS extension missing.

Recovery:

1. Check Docker Compose service names.
2. Check environment variables.
3. Confirm database is reachable from backend container or local process.
4. Run a minimal connection test.
5. Do not replace PostGIS with SQLite except for explicitly isolated unit tests.

PostGIS geometry error

Symptoms:

• invalid geometry,
• SRID missing,
• geometry column cannot be created.

Recovery:

1. Store all app geometry in EPSG:4326 unless a processing-specific CRS is required.
2. Validate GeoJSON before persistence.
3. Use Shapely for geometry validation.
4. Use PostGIS geometry column for persistent area/reference features.
5. Document any CRS transformation.

Frontend API mismatch

Symptoms:

• UI expects raw data but API returns envelope,
• errors not shown,
• undefined data states.

Recovery:

1. Update frontend API client, not individual components.
2. Normalize envelope handling centrally.
3. Ensure every component handles loading, empty, error and ready states.

Dependency installation failure

Symptoms:

• GDAL/Rasterio install errors,
• PyTorch package issue,
• platform binary mismatch.

Recovery:

1. Do not remove the feature from docs.
2. Add dependency note to docs/DEPENDENCY_LOCK_PLAN.md.
3. Implement interfaces and tests around pure-Python parts first.
4. Defer heavy binary package execution if needed, but leave adapter boundaries.

External data unavailable

Symptoms:

• WFS unavailable,
• Sentinel catalog unavailable,
• credentials missing.

Recovery:

1. Use demo fixtures.
2. Keep adapter disabled but present.
3. Return explicit external_service_unavailable status.
4. Do not fake that live data was fetched.

AI model unavailable

Symptoms:

• YOLO weights missing,
• SAM unavailable,
• GPU unavailable.

Recovery:

1. Build model registry and adapter interface.
2. Add CPU-safe mock inference only if marked as demo mode.
3. Keep output schema identical to real inference.
4. Do not present demo inference as production inference.

Test failures

Recovery:

1. Fix tests if implementation is wrong.
2. Fix implementation if test reflects contract.
3. Update specs only if they are clearly inconsistent.
4. Document unresolved failures in execution log.