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

3.9 KiB Raw Permalink Blame History Unescape Escape