# nasa/utm-apis architecture

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

- Interactive diagram: https://gitdiagram.com/nasa/utm-apis
- Repository: https://github.com/nasa/utm-apis

## Overview

##### Project Type and Purpose
- Type: Open-source collection of OpenAPI/Swagger specifications
- Purpose: Define and version the APIs (and common data models) used in NASA’s UTM research system. Users generate code (models, servers, clients) from these specs.

##### High-level Component Breakdown
- Git Repository
- Branches/tags: master (dev), RELEASE (sandbox snapshots)
- Shared Domain Specs (utm-domains)
- utm-domain-commons.yaml, geojson, metadata, performance-auth
- These define reusable data models
- API Spec Groups (each a separate “service”)
- fims-api
- fimsauthz-api
- nuss-operator-api
- oper-api
- public-safety-uss
- uss-api
- uss-discovery-api
- urep-api
- vehicle
- Tooling & External Services
- Swagger Editor (local or online)
- SwaggerHub (remote API repository & codegen)
- swagger-codegen CLI / JAR
- Code Generation Output
- Model-only libraries (Java Spring, etc.)
- Full server stubs or client SDKs

##### Relationships & Data Flows
- Shared Domain Specs → imported by each API’s swagger.yaml
- API Specs (swagger.yaml) → fed into codegen tool
- Codegen tool ↔ configuration JSON (library, java8, packages, validations)
- Codegen output → local ZIP / Maven artifact → integrated into service codebases
- Git branches/tags drive which spec versions are used for code generation (master vs RELEASE)

##### Architectural Patterns & Principles
- Specification-first design: All contracts live as YAML, not code
- Modularity: One folder per API; one folder for domains
- Reusability: Common data models factored into utm-domains
- Version control via Git branches/tags for release management
- Code generation automates stub and model creation to enforce consistency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Tools
    Editor["Swagger Editor<br/>(local/online)"]:::external
    Hub["SwaggerHub"]:::external

    %% Git Repository
    Repo["Git Repo<br/>master / RELEASE"]:::git

    %% Shared Domains
    subgraph "Shared Domain Specs" 
        direction TB
        Commons["utm-domain-commons.yaml"]:::spec
        GeoJSON["utm-domain-geojson.yaml"]:::spec
        Metadata["utm-domain-metadata.yaml"]:::spec
        PerformanceAuth["utm-domain-performance-auth.yaml"]:::spec
    end

    %% API Specifications
    subgraph "API Specifications" 
        direction TB
        FIMS["fims-api/swagger.yaml"]:::spec
        FIMSAuthZ1["fims-authz.yaml"]:::spec
        FIMSAuthZ2["nup-oauth2.yaml"]:::spec
        FIMSAuthZ3["nup-roles.yaml"]:::spec
        NUSS["nuss-operator-api/swagger.yaml"]:::spec
        OPER1["operator-api.yaml"]:::spec
        OPER2["nup-operator-api.yml"]:::spec
        OPER3["nup-operator-roles.yaml"]:::spec
        OPER4["user-to-roles.yaml"]:::spec
        PublicSafety["public-safety-uss/swagger.yaml"]:::spec
        UREP["urep-api/swagger.yaml"]:::spec
        USS["uss-api/swagger.yaml"]:::spec
        USSDisc["uss-discovery-api/swagger.yaml"]:::spec
        Vehicle["vehicle/swagger.yaml"]:::spec
    end

    %% Code Generation
    Codegen["Codegen Engine<br/>(swagger-codegen JAR)"]:::tooling
    Config["config.json"]:::tooling

    %% Generated Artifacts
    subgraph "Generated Artifacts"
        direction TB
        Models["Model Libraries"]:::output
        Stubs["Server Stubs / Client SDKs"]:::output
    end

    %% Connections: External to Repo and APIs
    Editor -->|edit/import| FIMS
    Editor -->|edit/import| FIMSAuthZ1
    Editor -->|edit/import| FIMSAuthZ2
    Editor -->|edit/import| FIMSAuthZ3
    Editor -->|edit/import| NUSS
    Editor -->|edit/import| OPER1
    Editor -->|edit/import| OPER2
    Editor -->|edit/import| OPER3
    Editor -->|edit/import| OPER4
    Editor -->|edit/import| PublicSafety
    Editor -->|edit/import| UREP
    Editor -->|edit/import| USS
    Editor -->|edit/import| USSDisc
    Editor -->|edit/import| Vehicle
    Hub -->|sync| FIMS
    Hub -->|sync| NUSS
    Hub -->|sync| OPER1

    %% Shared domains import
    FIMS -->|uses| Commons
    FIMS -->|uses| GeoJSON
    FIMS -->|uses| Metadata
    FIMS -->|uses| PerformanceAuth
    FIMSAuthZ1 -->|uses| Commons
    FIMSAuthZ2 -->|uses| Commons
    FIMSAuthZ3 -->|uses| Commons
    NUSS -->|uses| Commons
    OPER1 -->|uses| Commons
    OPER2 -->|uses| Commons
    OPER3 -->|uses| Commons
    OPER4 -->|uses| Commons
    PublicSafety -->|uses| Commons
    UREP -->|uses| Commons
    USS -->|uses| Commons
    USSDisc -->|uses| Commons
    Vehicle -->|uses| Commons

    %% Codegen pipeline
    FIMS -->|generate| Codegen
    FIMSAuthZ1 -->|generate| Codegen
    NUSS -->|generate| Codegen
    OPER1 -->|generate| Codegen
    PublicSafety -->|generate| Codegen
    UREP -->|generate| Codegen
    USS -->|generate| Codegen
    USSDisc -->|generate| Codegen
    Vehicle -->|generate| Codegen

    Config --> Codegen

    Codegen -->|--Dmodels| Models
    Codegen -->|--Dapis| Stubs

    %% Git metadata
    Repo --> FIMS
    Repo --> Commons
    Repo --> Codegen

    %% Click Events
    click Repo "https://github.com/nasa/utm-apis/blob/master/README.md"
    click Commons "https://github.com/nasa/utm-apis/blob/master/utm-domains/utm-domain-commons.yaml"
    click GeoJSON "https://github.com/nasa/utm-apis/blob/master/utm-domains/utm-domain-geojson.yaml"
    click Metadata "https://github.com/nasa/utm-apis/blob/master/utm-domains/utm-domain-metadata.yaml"
    click PerformanceAuth "https://github.com/nasa/utm-apis/blob/master/utm-domains/utm-domain-performance-auth.yaml"
    click FIMS "https://github.com/nasa/utm-apis/blob/master/fims-api/swagger.yaml"
    click FIMSAuthZ1 "https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/fims-authz.yaml"
    click FIMSAuthZ2 "https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/nup-oauth2.yaml"
    click FIMSAuthZ3 "https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/nup-roles.yaml"
    click NUSS "https://github.com/nasa/utm-apis/blob/master/nuss-operator-api/swagger.yaml"
    click OPER1 "https://github.com/nasa/utm-apis/blob/master/oper-api/operator-api.yaml"
    click OPER2 "https://github.com/nasa/utm-apis/blob/master/oper-api/nup-operator-api.yml"
    click OPER3 "https://github.com/nasa/utm-apis/blob/master/oper-api/nup-operator-roles.yaml"
    click OPER4 "https://github.com/nasa/utm-apis/blob/master/oper-api/user-to-roles.yaml"
    click PublicSafety "https://github.com/nasa/utm-apis/blob/master/public-safety-uss/swagger.yaml"
    click UREP "https://github.com/nasa/utm-apis/blob/master/urep-api/swagger.yaml"
    click USS "https://github.com/nasa/utm-apis/blob/master/uss-api/swagger.yaml"
    click USSDisc "https://github.com/nasa/utm-apis/blob/master/uss-discovery-api/swagger.yaml"
    click Vehicle "https://github.com/nasa/utm-apis/blob/master/vehicle/swagger.yaml"

    %% Styles
    classDef spec fill:#E0F7FA,stroke:#006064,color:#006064
    classDef tooling fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef output fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef git fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
```
