# isaiahharvi/orion architecture

> Architecture diagram of the GitHub repository isaiahharvi/orion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isaiahharvi/orion
- Repository: https://github.com/isaiahharvi/orion

## Overview

##### Project type and purpose
- Full-stack, containerized web application for real-time observation and intelligence gathering.
- Frontend: SvelteKit SPA (src/app).
- Backend/API: Python service exposing endpoints (src/services/api).
- Data pipeline pieces: model logic (src/services/model), scan utilities (src/services/scans), and Postgres persistence (src/services/postgres).
- Docker Compose orchestration for GUI, API, and Postgres.

##### File structure
- Top-level: devcontainer for local dev, deploy for production Dockerfiles and compose files, data for static assets/checkpoints, scripts for helpers, src/app for UI, src/services for backend logic, tests.
- The presence of multiple src/services subfolders hints at a layered backend (API controllers, ML model logic, data scans, DB adapters).
- compose.yml and deploy/compose.yml define three main services: gui, api, postgres.
- Scripts like get_data.sh, setup_dev.sh indicate data ingestion/setup pipelines.

##### Extract key architecture info from README
- Docker Compose profile “gui” brings up both frontend and backend.
- Environment variable VITE_API_URL for pointing the frontend at the API.
- API docs exposed under /api/docs.
- External data sources: UAV telemetry, NEXRAD radar, AIS tracking.

##### Main components
a. Frontend (GUI) container
– SvelteKit application (port 5173)
– Fetches data via REST/WebSocket from API
b. API container
– Python service (FastAPI or similar)
– Routes in src/services/api/api.py
– Invokes model logic (src/services/model) and scan utilities (src/services/scans)
– Orchestrates data ingestion and transformation
c. Database (Postgres) container
– Persistent store for raw and processed data (deploy/postgres)
– DB migrations or seed data scripts (get_db_sample.py, start_db.sh)
d. Data sources (external)
– UAV feed
– NEXRAD stations (CSV + live)
– AIS vessel tracking
e. Data folder (local)
– Checkpoints folder with Keras ML model
– Static files (nexrad_stations.csv)

##### Interactions and data flow
- User → Browser → Frontend (HTTP/WS)
- Frontend → API (HTTP)
- API → Postgres (SQL via store.py)
- API → Model logic (local ML inference using checkpoints)
- API → Scan modules (fetch/parse NEXRAD, AIS, UAV feeds)
- Scheduled or on-demand scripts (get_data.sh) populate raw data directory / DB
- Optionally background tasks in the API container trigger model retraining or inference

##### Architectural patterns & design principles
- Layered backend: API (controllers) → services/model & services/scans (business logic) → services/postgres (data access)
- Container-per-concern: GUI, API, Postgres
- Infrastructure as code: Docker Compose and deploy scripts govern deployment.
- Dev container for reproducible local development.
- Clear separation of concerns: UI vs domain logic vs persistence.

##### Technologies & frameworks
- Frontend: SvelteKit, Vite, Tailwind, TypeScript
- Backend: Python 3.x, FastAPI (implied), PyTorch/Keras for ML
- Database: PostgreSQL
- Orchestration: Docker Compose, Devcontainer
- CI: GitHub Actions (lint and unit tests for both TS and Python)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::user
    Browser["Browser"]:::user
    User -->|"interact"| Browser
    Browser -->|"HTTP/WebSocket"| GUI

    %% GUI Container
    subgraph "GUI Container"
      direction TB
      GUI["SvelteKit UI\n(port 5173)"]:::frontend
    end
    click GUI "https://github.com/isaiahharvi/orion/tree/main/src/app"

    %% API Container
    subgraph "API Container"
      direction TB
      APIService["Python API Service\n(src/services/api/api.py)"]:::backend
      Model["Model Engine\n(src/services/model)"]:::logic
      Scan["Scan Utilities\n(src/services/scans)"]:::logic
      DBAdapter["DB Adapter\n(src/services/postgres/store.py)"]:::database
      APIService -->|calls| Model
      APIService -->|calls| Scan
      APIService -->|queries| DBAdapter
    end
    click APIService "https://github.com/isaiahharvi/orion/blob/main/src/services/api/api.py"
    click Model "https://github.com/isaiahharvi/orion/tree/main/src/services/model"
    click Scan "https://github.com/isaiahharvi/orion/tree/main/src/services/scans"
    click DBAdapter "https://github.com/isaiahharvi/orion/blob/main/src/services/postgres/store.py"

    %% Data Files Folder
    subgraph "Local Data Folder"
      direction TB
      CP["tornado_detector_baseline.keras"]:::data
      Stations["nexrad_stations.csv"]:::data
    end
    click CP "https://github.com/isaiahharvi/orion/blob/main/data/checkpoints/tornado_detector_baseline.keras"
    click Stations "https://github.com/isaiahharvi/orion/blob/main/data/nexrad_stations.csv"
    DataScripts["Data Ingestion Scripts"]:::scripts
    click DataScripts "https://github.com/isaiahharvi/orion/blob/main/scripts/get_data.sh"
    click DataScripts "https://github.com/isaiahharvi/orion/blob/main/scripts/setup_dev.sh"
    DataScripts -->|"writes"| CP
    DataScripts -->|"writes"| Stations
    CP -->|used by| Model
    Stations -->|used by| Scan

    %% External Data Sources
    UAV["UAV Telemetry"]:::external
    NEXRAD["NEXRAD Radar"]:::external
    AIS["AIS Vessel Tracking"]:::external
    UAV -->|feeds| Scan
    NEXRAD -->|feeds| Scan
    AIS -->|feeds| Scan

    %% Database Container
    subgraph "Postgres Container"
      direction TB
      PostgresDB["PostgreSQL DB"]:::database
    end
    click PostgresDB "https://github.com/isaiahharvi/orion/blob/main/deploy/postgres/compose.yml"
    DBAdapter -->|read/write| PostgresDB

    %% Orchestration & Config
    subgraph "Orchestration & Deployment"
      direction TB
      LocalCompose["Docker Compose (Local)"]:::infra
      ProdCompose["Docker Compose (Prod)"]:::infra
      API_Dockerfile["API Dockerfile"]:::infra
      GUI_Dockerfile["GUI Dockerfile"]:::infra
      DevContainer["Devcontainer Config"]:::infra
      LocalCompose --> GUI
      LocalCompose --> APIService
      LocalCompose --> PostgresDB
      ProdCompose --> GUI
      ProdCompose --> APIService
      ProdCompose --> PostgresDB
    end
    click LocalCompose "https://github.com/isaiahharvi/orion/blob/main/compose.yml"
    click ProdCompose "https://github.com/isaiahharvi/orion/blob/main/deploy/compose.yml"
    click API_Dockerfile "https://github.com/isaiahharvi/orion/tree/main/deploy/api/Dockerfile"
    click GUI_Dockerfile "https://github.com/isaiahharvi/orion/tree/main/deploy/gui/Dockerfile"
    click DevContainer "https://github.com/isaiahharvi/orion/blob/main/.devcontainer/devcontainer.json"

    %% Interactions
    GUI -->|REST API| APIService

    %% Styling
    classDef user fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef frontend fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef backend fill:#32CD32,stroke:#000,stroke-width:1px
    classDef logic fill:#228B22,stroke:#000,stroke-width:1px
    classDef database fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef data fill:#FFE4B5,stroke:#000,stroke-width:1px
    classDef scripts fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef infra fill:#A9A9A9,stroke:#000,stroke-width:1px
```
