# Repository Guidelines

## Project Overview

SkyNav SpaceCom is a dual-domain re-entry debris hazard analysis platform that bridges space-domain prediction with aviation-domain decision support. It visualises space objects on a 3D globe (CesiumJS) and is designed to evolve into a full hazard analysis and decision-support system for ANSPs and aviation safety organisations.

Key planning documents:
- `docs/Overview.md` — shortest summary of the programme
- `docs/Roadmap.md` — staged product delivery view (Phases 0–7)
- `docs/Implementation_Plan.md` — sprint-oriented coding plan (Phases 0–10)
- `docs/Master_Plan.md` — authoritative detailed specification

## Current Repository State

The original prototype code has been archived to `original_code/` (gitignored as reference). The working tree is being rebuilt from scratch. The repo currently contains only:

```
AGENTS.md            This file
docs/                Planning and architecture documents
original_code/       Archived prototype (gitignored, reference only)
```

The archived prototype in `original_code/` contains:
```
original_code/backend/app/main.py     FastAPI app with a single /czml/test endpoint
original_code/backend/Dockerfile      Python 3.11-slim, installs fastapi + uvicorn
original_code/frontend/public/        Static HTML/JS — CesiumJS 1.110 globe + OSM tiles
original_code/frontend/public/config.js  API_BASE_URL = http://aegis.sbln.bxl.skynav.cloud:8000
original_code/db/schema.sql           PostGIS + TimescaleDB schema (objects, orbits, conjunctions, reentry_predictions)
original_code/docker-compose.yml      Three services: nginx frontend, FastAPI backend, TimescaleDB/PostGIS db
original_code/worker/fetch.py         Placeholder TLE/CDM ingest worker
original_code/.env                    DB credentials (POSTGRES_DB/USER/PASSWORD=spacecom)
```

## Target Architecture (from docs)

The target stack per `docs/Overview.md` and `docs/Master_Plan.md`:

- **Frontend** — Next.js + TypeScript + CesiumJS
- **Backend** — FastAPI (Python), async, with WebSocket API
- **Workers** — Celery workers for simulation, propagation, ingest (isolated from app Redis)
- **Database** — TimescaleDB (PostgreSQL + PostGIS) for time-series orbital data
- **Cache/Queue** — Redis (split trust domains: app state vs worker traffic)
- **Object storage** — MinIO for simulation outputs and reports
- **Renderer** — Network-isolated renderer for report generation
- **Deployment** — Docker Compose on self-hosted VPS; CI/CD via self-hosted GitLab

## Database Schema (from prototype)

Key tables (defined in `original_code/db/schema.sql`):

- `objects` — space object catalog (NORAD ID, orbital params, mass)
- `orbits` — time-series positions (TimescaleDB hypertable, PostGIS geography)
- `conjunctions` — conjunction alerts with probability of collision (TCA, miss distance, PoC)
- `reentry_predictions` — re-entry windows with geographic footprints

## Build, Test, and Development Commands

No test framework, linter, or formatter is configured yet.

The prototype stack was started with:
```
docker compose up --build
```

Frontend was available at `http://localhost:8080`, backend API at `http://localhost:8000`.
The deployment environment is `aegis.sbln.bxl.skynav.cloud`.

## Git & Source Control

Hosted on GitLab at `gemini.skynavintl.com:10090/root/spacecom`. Two commits exist:
- `05f87e0` Initial commit
- `2c49d7c` base sys done. shift to vs code

Conventional commits format is the target standard. The `.gitignore` covers Python, Node, Docker, database artifacts, environment files, and the `original_code/` archive.

## Delivery Principles (from docs)

- Safety-critical changes require human review
- Contracts are the authoritative source of commercial entitlements
- Self-hosted GitLab is the authoritative CI/CD platform
- Phase 0 architectural and legal blockers must be cleared before commitment-heavy implementation
- Commercial enforcement must not interrupt active operational incidents