# uworbital/obc-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/uworbital/obc-firmware
- Repository: https://github.com/uworbital/obc-firmware

## Overview

##### Project Type and Purpose
- This is a multi‐component CubeSat software stack developed by UW Orbital’s firmware team.
- It comprises:
a. On‐Board Computer (OBC) firmware (embedded C/C++ running on TI RM46 with FreeRTOS)
b. Hardware‐in‐the‐Loop (HIL) simulator (C++ examples and log‐sink)
c. Ground Station (GS) full‐stack app:
- Backend (Python FastAPI REST API + PostgreSQL)
- Frontend (TypeScript/React apps for ARO and MCC)
d. Shared interfaces and libraries (serial port, FEC, AES, GNC code, Reliance Edge FS, etc.)
e. Tests and CI scripts

##### File Structure Overview
- Top‐level build & CI: CMakeLists.txt, cmake/, scripts/, .github/workflows/
- ‘obc/’: firmware source split into bootloader (bl/), application (app/), shared HAL, tools, examples
- ‘interfaces/’: C libraries for OBC↔GS packet pack/unpack, CRC, FEC, telemetry
- ‘libs/’: third‐party & generated code (cserialport, libcorrect, tiny_aes, posix_freertos, GNC code)
- ‘hil/’: HIL C++ examples and log sink
- ‘gs/’:
- gs/backend/: FastAPI service, middleware, v1 API (aro & mcc endpoints), database ORM
- gs/frontend/: two Deno/Vite React apps (ARO and MCC) served on localhost
- ‘test/’ & ‘python_test/’: C/C++ unit tests, Python unit tests
- Configuration & docs: README.md, gs/POSTGRESQL_SETUP.md, scripts, compose-dev.yaml

##### README Insights
- Clarifies cross‐platform build setup (WSL2, Mac, Linux, Windows)
- Describes multi‐target CMake builds (OBC, GS, Test, Examples)
- Outlines technology stack: C/C++ with HALCoGen & Code Composer, Python FastAPI, React/TS, Deno, PostgreSQL

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flight Segment
    subgraph "Flight Segment"
        direction TB
        OBC_BL["OBC Bootloader\n(obc/bl)\nC/C++"]:::embedded
        subgraph "OBC Application Firmware\n(obc/app)\n(C, FreeRTOS)"
            direction TB
            APP_DRIVERS["Drivers\n(obc/app/drivers)"]:::embedded
            APP_HAL["HAL\n(obc/app/hal)"]:::embedded
            APP_MODULES["Application Modules\n(obc/app/modules)"]:::embedded
            APP_RTOS["RTOS Config\n(obc/app/rtos)"]:::embedded
            APP_SYS["System Services\n(obc/app/sys)"]:::embedded
            APP_RE["Reliance Edge FS\n(obc/app/reliance_edge)"]:::embedded
        end
        OBC_SHARED["Shared HAL & Metadata\n(obc/shared)"]:::embedded
        INTERFACES["Packet Interfaces\n(interfaces)"]:::embedded
    end

    %% HIL Simulator
    subgraph "Hardware-in-the-Loop Simulator\n(hil)"
        direction TB
        HIL_EX["Example Simulations\n(hil/examples)"]:::sim
        HIL_LOG["Log Sink Service\n(hil/logsink)"]:::sim
    end

    %% Libraries
    subgraph "Shared & Third-Party Libraries\n(libs)"
        direction TB
        LIB_SERIAL["Serial Port\n(libs/cserialport)"]:::lib
        LIB_FEC["Reed-Solomon FEC\n(libs/libcorrect)"]:::lib
        LIB_AES["Tiny AES\n(libs/tiny_aes)"]:::lib
        LIB_POSIX["POSIX FreeRTOS\n(libs/posix_freertos)"]:::lib
        LIB_GNC["GNC Code\n(libs/gnc_code)"]:::lib
    end

    %% Ground Segment
    subgraph "Ground Segment"
        direction TB
        subgraph "GS Backend Service\n(gs/backend)\n(Python FastAPI)"
            direction TB
            GS_API["API Core & Startup\n(gs/backend/api)"]:::backend
            GS_MW["API Middleware\n(gs/backend/api/middleware)"]:::backend
            GS_ARO["v1 ARO Endpoints\n(gs/backend/api/v1/aro)"]:::backend
            GS_MCC["v1 MCC Endpoints\n(gs/backend/api/v1/mcc)"]:::backend
            GS_CONF["Config Management\n(gs/backend/config)"]:::backend
            GS_DBENG["DB Engine & ORM\n(gs/backend/data/database)"]:::backend
            GS_TABLES["Data Models & Tables\n(gs/backend/data/tables)"]:::backend
            GS_COMMON["Common Utils & Errors\n(gs/backend/common\n& exceptions)"]:::backend
            GS_MAIN["Main Entrypoint\n(gs/backend/main.py)"]:::backend
        end
        POSTGRES["PostgreSQL\n(database)"]:::db
        GS_UI_ARO["ARO Frontend\n(gs/frontend/aro)\n(React/TS)"]:::frontend
        GS_UI_MCC["MCC Frontend\n(gs/frontend/mcc)\n(React/TS)"]:::frontend
    end

    %% CI/CD & Build Tools
    subgraph "CI/CD & Build Tools"
        direction TB
        CI_CMAKE["CMake & Scripts\n(CMakeLists.txt, cmake/, scripts/)"]:::tool
        CI_GHA["GitHub Actions Workflows\n(.github/workflows/)"]:::tool
    end

    %% Connections
    OBC_BL -->|"boots into"| APP_DRIVERS
    APP_DRIVERS --> APP_HAL --> APP_MODULES --> APP_RTOS --> APP_SYS
    APP_MODULES --> APP_RE
    APP_SYS --> OBC_SHARED --> INTERFACES
    INTERFACES -->|"AX.25 over CC1120"| GS_API
    APP_SYS -->|"simulate calls"| HIL_EX --> HIL_LOG
    LIB_SERIAL --> INTERFACES
    LIB_FEC --> INTERFACES
    LIB_AES --> INTERFACES
    LIB_POSIX --> APP_RTOS
    LIB_GNC --> APP_MODULES
    CI_CMAKE --> OBC_BL
    CI_CMAKE --> GS_API
    CI_CMAKE --> GS_UI_ARO
    CI_CMAKE --> GS_UI_MCC
    CI_GHA --> CI_CMAKE

    GS_UI_ARO -->|"HTTP/REST"| GS_API
    GS_UI_MCC -->|"HTTP/REST"| GS_API
    GS_API -->|"read/write"| POSTGRES

    %% Click Events
    click OBC_BL "https://github.com/uworbital/obc-firmware/tree/main/obc/bl"
    click APP_DRIVERS "https://github.com/uworbital/obc-firmware/tree/main/obc/app/drivers"
    click APP_HAL "https://github.com/uworbital/obc-firmware/tree/main/obc/app/hal"
    click APP_RTOS "https://github.com/uworbital/obc-firmware/tree/main/obc/app/rtos"
    click APP_SYS "https://github.com/uworbital/obc-firmware/tree/main/obc/app/sys"
    click APP_RE "https://github.com/uworbital/obc-firmware/tree/main/obc/app/reliance_edge"
    click APP_MODULES "https://github.com/uworbital/obc-firmware/tree/main/obc/app/modules"
    click OBC_SHARED "https://github.com/uworbital/obc-firmware/tree/main/obc/shared"
    click HIL_EX "https://github.com/uworbital/obc-firmware/tree/main/hil/examples"
    click HIL_LOG "https://github.com/uworbital/obc-firmware/tree/main/hil/logsink"
    click LIB_SERIAL "https://github.com/uworbital/obc-firmware/tree/main/libs/cserialport"
    click LIB_FEC "https://github.com/uworbital/obc-firmware/tree/main/libs/libcorrect"
    click LIB_AES "https://github.com/uworbital/obc-firmware/tree/main/libs/tiny_aes"
    click LIB_POSIX "https://github.com/uworbital/obc-firmware/tree/main/libs/posix_freertos"
    click LIB_GNC "https://github.com/uworbital/obc-firmware/tree/main/libs/gnc_code"
    click GS_API "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/api"
    click GS_MW "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/api/middleware"
    click GS_ARO "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/api/v1/aro"
    click GS_MCC "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/api/v1/mcc"
    click GS_CONF "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/config"
    click GS_DBENG "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/data/database"
    click GS_TABLES "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/data/tables"
    click GS_COMMON "https://github.com/uworbital/obc-firmware/tree/main/gs/backend/common"
    click GS_MAIN "https://github.com/uworbital/obc-firmware/blob/main/gs/backend/main.py"
    click GS_UI_ARO "https://github.com/uworbital/obc-firmware/tree/main/gs/frontend/aro"
    click GS_UI_MCC "https://github.com/uworbital/obc-firmware/tree/main/gs/frontend/mcc"
    click CI_CMAKE "https://github.com/uworbital/obc-firmware/blob/main/CMakeLists.txt"
    click CI_GHA "https://github.com/uworbital/obc-firmware/tree/main/.github/workflows/"

    %% Styles
    classDef embedded fill:#e0f3ff,stroke:#1f77b4,color:#000;
    classDef sim fill:#fff0e0,stroke:#ff7f0e,color:#000;
    classDef backend fill:#e0ffe0,stroke:#2ca02c,color:#000;
    classDef db fill:#f0e0ff,stroke:#9467bd,color:#000;
    classDef frontend fill:#f0e0ff,stroke:#9467bd,color:#000;
    classDef lib fill:#f9f9f9,stroke:#7f7f7f,color:#000;
    classDef tool fill:#dcdcdc,stroke:#8c8c8c,color:#000;
```
