# r-spacex/spacex-api architecture

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

- Interactive diagram: https://gitdiagram.com/r-spacex/spacex-api
- Repository: https://github.com/r-spacex/spacex-api

## Overview

##### Project type and purpose
- This is a monolithic, Node.js‐based REST API service (no UI) that exposes SpaceX telemetry: launches, rockets, capsules, payloads, starlink, landpads, etc.
- It combines a data‐ingestion pipeline (cron jobs) with an Express‐powered HTTP API (v4 & v5 endpoints), backed by a document database (e.g. MongoDB via the models/ folder).

##### File structure
- Entry points:
- server.js & app.js – initialize Express, mount middleware, routes, start listener.
- start.sh & Dockerfile – container startup script & image definition.
- Ingestion pipeline (jobs/):
- One file per resource (jobs/launches.js, jobs/starlink.js, etc.) plus jobs/worker.js – invoked on a schedule (cron).
- Data layer (models/):
- One model per entity (models/rockets.js, models/launches.js, models/users.js, etc.), likely implemented with Mongoose.
- API layer (routes/):
- routes/[resource]/v4 and routes/[resource]/v5 – route definitions and transform helpers (_transform-query.js, _transform-response.js).
- routes/index.js & routes/admin – aggregate routers and mount under `/v4`, `/v5`.
- Cross-cutting (middleware/):
- auth.js, authz.js, cache.js, logger.js, errors.js, response-time.js – build a middleware chain.
- Utilities & integrations (lib/):
- healthchecks integration, constants, shared utils.
- CI/CD & Deployment:
- .github/workflows – build/test/deploy pipelines
- Dockerfile & .dockerignore – image build
- healthchecks badges in README – monitor cron health.

##### README for additional insights
- Public API exposed at `https://api.spacexdata.com/v5/...`
- Cron jobs report to healthchecks.io
- Docker Hub image available for deployment
- No front‐end; external consumers hit your API directly.

a. Main components
- Cron Job Scheduler (jobs/)
- External Data Sources (launch‐library v2, SpaceX official endpoints)
- Document Database (MongoDB cluster)
- Express REST API (app.js/server.js + routes/, middleware/)
- External services: Healthchecks.io, GitHub Actions CI/CD, Docker Registry
- API Clients: mobile/web apps, third-party integrations
b. Relationships & interactions
- Scheduler jobs ← fetch ← External Data Sources
- Scheduler jobs → write → Database
- API Server → read → Database
- Clients → HTTP → API Server
- Scheduler jobs & API Server → ping → Healthchecks.io
- GitHub Actions → build & push → Docker Registry → deploy → container runs API + scheduler
c. Architectural patterns & design principles
- Layered architecture:
– Presentation/API layer (routes + controllers)
– Business layer (jobs + model logic)
– Data access layer (models)
- Modular versioned routing (v4, v5 folders)
- Middleware chain for cross‐cutting concerns (auth, caching, logging, error handling)
- Containerized deployment, externalized configuration
d. Key technologies
- Node.js & Express
- MongoDB (via Mongoose models)
- healthchecks.io for uptime/cron monitoring
- Docker & Dockerfile
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ExternalData["External Data Sources"]:::externaldata
    Clients["API Clients"]:::external
    Healthchecks["Healthchecks.io"]:::external
    GitHubActions["GitHub Actions CI/CD"]:::external
    DockerRegistry["Docker Registry"]:::external
    Container["Deployment Container"]:::core

    %% Cron Scheduler and Jobs
    subgraph "Cron Job Scheduler" 
        direction TB
        Worker["worker.js"]:::core
        LaunchesJob["launches.js"]:::core
        StarlinkJob["starlink.js"]:::core
        CapsulesJob["capsules.js"]:::core
    end

    %% Database
    MongoDB["MongoDB Cluster"]:::datastore

    %% API Server
    subgraph "Express API Server" 
        direction TB
        AppInit["app.js"]:::core
        ServerInit["server.js"]:::core
        subgraph "Middleware Chain"
            direction TB
            MiddlewareIndex["middleware/index.js"]:::core
        end
        subgraph "Versioned Routes"
            direction TB
            RoutesIndex["routes/index.js"]:::core
            subgraph "/launches"
                direction TB
                LaunchesV4["v4"]:::core
                LaunchesV5["v5"]:::core
            end
        end
    end

    %% Data Access Layer
    subgraph "Models (Data Access Layer)"
        direction TB
        ModelsIndex["models/index.js"]:::core
        ModelsLaunches["models/launches.js"]:::core
    end

    %% Utilities & Healthchecks Integration
    subgraph "Utilities & Healthchecks"
        direction TB
        Constants["lib/constants.js"]:::core
        HealthUtils["lib/utils/healthcheck.js"]:::core
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        CodeQL[".github/workflows/codeql-analysis.yml"]:::external
        DeployWf[".github/workflows/deploy.yml"]:::external
        Dockerfile["Dockerfile"]:::external
        StartSh["start.sh"]:::external
    end

    %% Connections
    ExternalData -->|"fetch data"| Worker
    Worker -->|"ingest"| MongoDB
    LaunchesJob --> MongoDB
    StarlinkJob --> MongoDB
    CapsulesJob --> MongoDB

    Worker -->|ping| Healthchecks
    AppInit --> ServerInit
    Clients -->|"HTTP"| ServerInit
    ServerInit -->|"uses"| MiddlewareIndex
    MiddlewareIndex --> RoutesIndex
    RoutesIndex --> LaunchesV4
    RoutesIndex --> LaunchesV5
    LaunchesV4 --> MongoDB
    LaunchesV5 --> MongoDB
    ServerInit -->|ping| Healthchecks

    ModelsIndex --> ModelsLaunches
    RoutesIndex --> ModelsLaunches

    Constants --> HealthUtils
    HealthUtils --> Healthchecks

    GitHubActions -->|run pipelines| CodeQL
    GitHubActions --> DeployWf
    DeployWf --> DockerRegistry
    DockerRegistry -->|deploy image| Container

    Container --> Worker
    Container --> ServerInit

    %% Click Events
    click Worker "https://github.com/r-spacex/spacex-api/blob/master/jobs/worker.js"
    click LaunchesJob "https://github.com/r-spacex/spacex-api/blob/master/jobs/launches.js"
    click StarlinkJob "https://github.com/r-spacex/spacex-api/blob/master/jobs/starlink.js"
    click CapsulesJob "https://github.com/r-spacex/spacex-api/blob/master/jobs/capsules.js"
    click AppInit "https://github.com/r-spacex/spacex-api/blob/master/app.js"
    click ServerInit "https://github.com/r-spacex/spacex-api/blob/master/server.js"
    click Dockerfile "https://github.com/r-spacex/spacex-api/tree/master/Dockerfile"
    click StartSh "https://github.com/r-spacex/spacex-api/blob/master/start.sh"
    click RoutesIndex "https://github.com/r-spacex/spacex-api/blob/master/routes/index.js"
    click LaunchesV4 "https://github.com/r-spacex/spacex-api/tree/master/routes/launches/v4"
    click LaunchesV5 "https://github.com/r-spacex/spacex-api/tree/master/routes/launches/v5"
    click MiddlewareIndex "https://github.com/r-spacex/spacex-api/blob/master/middleware/index.js"
    click ModelsIndex "https://github.com/r-spacex/spacex-api/blob/master/models/index.js"
    click ModelsLaunches "https://github.com/r-spacex/spacex-api/blob/master/models/launches.js"
    click Constants "https://github.com/r-spacex/spacex-api/blob/master/lib/constants.js"
    click HealthUtils "https://github.com/r-spacex/spacex-api/blob/master/lib/utils/healthcheck.js"
    click CodeQL "https://github.com/r-spacex/spacex-api/blob/master/.github/workflows/codeql-analysis.yml"
    click DeployWf "https://github.com/r-spacex/spacex-api/blob/master/.github/workflows/deploy.yml"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#007ACC,stroke-width:1px
    classDef datastore fill:#FFE4B3,stroke:#CC8400,stroke-width:1px
    classDef external fill:#E2FFD8,stroke:#2E8B57,stroke-width:1px
    classDef externaldata fill:#F0F0F0,stroke:#808080,stroke-width:1px
```
