SpaceCom/docs/Implementation_Plan.md

SpaceCom Implementation Plan

Purpose

This document turns the master plan into an implementation-oriented coding plan. It is focused on phases of engineering work and sprint-style delivery, not on full architectural detail.

Delivery Model

The implementation plan assumes:

• self-hosted GitLab as the delivery platform
• Docker Compose as the baseline deployment model
• contracts as the authoritative entitlement source
• Phase 0 blockers cleared before major coding commitments
• safety-critical, auth, and regulatory-sensitive changes always require human review

Phase 0: Pre-Build Decisions

Objective:

• clear the decisions that would otherwise force rework

Sprint 0 outcomes:

• Space-Track AUP architecture decision recorded
• Cesium commercial licence executed
• GitLab CI/CD authority confirmed
• contract-driven entitlement model confirmed
• Redis trust split approved
• initial ADR set aligned with these decisions

Exit criteria:

• no unresolved blocker remains that would change ingest, licensing, or deployment direction

Phase 1: Foundation Sprints

Objective:

• establish the platform baseline and developer workflow

Sprint 1.1

• backend project structure and FastAPI scaffolding
• frontend project structure and Next.js scaffolding
• Docker Compose topology
• TimescaleDB/PostGIS baseline schema
• GitLab CI skeleton
• docs tree, ADR format, AGENTS.md, changelog baseline

Sprint 1.2

• auth baseline: JWT, cookies, MFA foundation
• RBAC and role checks
• liveness and readiness endpoints
• structured logging
• security scan hooks and pre-commit
• first-login acceptance gates for ToS/AUP/Privacy Notice

Exit criteria:

• full stack starts cleanly
• CI runs on every merge request
• auth and role boundaries exist
• baseline docs and controls are in place

Phase 2: Data and Ingest Sprints

Objective:

• make the platform ingest and manage real operational data safely

Sprint 2.1

• object catalog CRUD
• TLE ingest
• ingest worker wiring
• source validation and checksum checks
• basic data freshness indicators

Sprint 2.2

• DISCOS import
• space weather ingest
• retention policy scaffolding
• ingest metrics and failure alerts
• first degraded-mode backend signals

Exit criteria:

• core upstream data can be ingested, validated, stored, and monitored

Phase 3: Propagation and Physics Core

Objective:

• deliver the first real analysis engine

Sprint 3.1

• frame/time utilities
• SGP4 propagation
• frame transformation validation
• initial CZML generation

Sprint 3.2

• numerical decay predictor
• atmospheric inputs
• upper/lower atmosphere model interfaces for terminal descent
• model versioning hooks
• prediction input validation

Exit criteria:

• the platform can produce technically valid propagated and decay outputs with traceable inputs

Phase 4: Simulation and Hazard Engine

Objective:

• build the uncertainty and event-analysis layer

Sprint 4.1

• Monte Carlo job orchestration
• Celery chord flow
• worker resource controls
• result aggregation guards

Sprint 4.2

• breakup logic and sub/trans-sonic fragment model baseline
• fragment shape, tumble, and descent-assumption reference data
• corridor generation
• object/event linking
• first event orchestration path

Exit criteria:

• multi-run hazard outputs are generated safely, bounded, and auditable

Phase 5: Operational Frontend

Objective:

• make the product usable for analysts and operators

Sprint 5.1

• globe and layer controls
• timeline strip
• object/event navigation
• degraded-state presentation

Sprint 5.2

• alert centre
• acknowledgement flow
• decision prompts
• keyboard-first interaction paths

Exit criteria:

• operators can see, interpret, and act on platform outputs in the UI

Phase 6: Event Workflow and Reporting

Objective:

• support full event handling, not just display

Sprint 6.1

• event detail page
• event state transitions
• report job submission and tracking
• WebSocket event flow

Sprint 6.2

• report rendering pipeline
• export storage flow
• report audit trail
• offline/reconnect handling

Exit criteria:

• an end-to-end event can be analysed, reviewed, and reported through the platform

Phase 7: Reliability, Safety, and Compliance Hardening

Objective:

• turn a capable system into an operationally defensible one

Sprint 7.1

• observability dashboards
• SLO instrumentation
• alerting rules
• incident-response runbook alignment

Sprint 7.2

• privacy workflows
• retention and pseudonymisation tasks
• safety-case artefacts linkage
• audit-log separation and integrity controls

Exit criteria:

• the system is observable, auditable, and aligned with documented operational obligations

Phase 8: Aviation Product Expansion

Objective:

• strengthen the ANSP-facing differentiation

Sprint 8.1

• FIR intersection and aviation-context outputs
• aircraft exposure and vulnerability scoring
• uncertainty display refinements
• operator-facing airspace impact summaries
• conservative-baseline comparison outputs

Sprint 8.2

• shadow mode behaviour
• multi-ANSP coordination foundations
• NOTAM-adjacent workflow support
• live air-traffic density and route inputs for air-risk products

Exit criteria:

• the aviation-side product layer is credible for shadow deployment and stakeholder review

Phase 9: Space Operator Expansion

Objective:

• extend the shared core into upstream customer workflows

Sprint 9.1

• owned-object data model and access rules
• API key lifecycle
• portal foundations

Sprint 9.2

• controlled re-entry planner
• CCSDS OEM/CDM/RDM export
• partner-facing integration workflows

Exit criteria:

• the shared physics core now supports both downstream aviation and upstream space-operator use

Phase 10: Deployment Readiness and Evidence

Objective:

• prepare for shadow deployment and external scrutiny

Sprint 10.1

• validation and backcasting workflow
• named historical replay corpus and conservative-baseline comparisons
• tender-grade KPI and air-risk validation pack
• shadow reporting outputs
• deployment gating refinements

Sprint 10.2

• final compliance artefacts
• ESA software assurance artefacts: SRS, SDD, user manual, test report
• release checklist completion
• operational readiness review
• first shadow deployment package

Exit criteria:

• the platform is ready for controlled external deployment and evidence-based review

Cross-Cutting Workstreams

The following run continuously across phases rather than in only one sprint:

• security architecture and dependency hygiene
• documentation and ADR maintenance
• test coverage and validation artefacts
• safety-case traceability
• legal/commercial gating
• performance and capacity reviews
• procurement traceability and bid artefact maintenance

Recommended Execution Pattern

For actual delivery, each sprint should end with:

• a demoable increment
• updated docs
• updated ADRs where needed
• passing CI
• explicit review of safety/compliance impacts

Relationship to Other Docs

• Overview.md gives the shortest summary
• Roadmap.md gives the big-picture staged view
• MASTER_PLAN.md remains the authoritative detailed plan