# nasa-across/across-server architecture

> Architecture diagram of the GitHub repository nasa-across/across-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nasa-across/across-server
- Repository: https://github.com/nasa-across/across-server

## Overview

NASA ACROSS Server exposes REST APIs for science situational-awareness resources and tools. A client request enters the FastAPI application and versioned API; authentication and authorization protect applicable operations, whose services implement domain behavior and access persisted records. The domain spans observatory/telescope/instrument resources, observation requests and schedules, observations, broker alerts/events, and SSA utilities, alongside user and group access management. The README documents the router–auth–service–data layering; sampled source confirms application setup, database initialization, and selected service behavior. Unsampled subsystem links are limited to documented architecture and the file tree.

Main entry points: [`across_server/routes/v1`](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1) (Version 1 API), [`across_server/db/database.py`](https://github.com/nasa-across/across-server/blob/main/across_server/db/database.py) (DB sessions), [`across_server/main.py`](https://github.com/nasa-across/across-server/blob/main/across_server/main.py) (FastAPI app), [`across_server/auth`](https://github.com/nasa-across/across-server/tree/main/across_server/auth) (Token authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["FastAPI app<br/>[main.py]"]
  node_v1["Version 1 API"]
end

subgraph group_identity["Identity access"]
  node_auth["Token authentication"]
  node_permissions["Role permissions<br/>[strategies.py]"]
end

subgraph group_science["Science operations"]
  node_catalog["Observatory catalog"]
  node_telescopes["Telescope instruments"]
  node_requests["Observation requests"]
  node_schedules["Schedules"]
  node_observations["Observations"]
  node_broker["Broker alerts events"]
  node_ssa_tools["SSA tools"]
end

subgraph group_admin["Accounts administration"]
  node_users["User accounts"]
  node_groups["Groups and roles"]
  node_service_accounts["Service accounts"]
end

subgraph group_infra["Shared infrastructure"]
  node_db_session["DB sessions<br/>[database.py]"]
  node_models["SQLAlchemy models<br/>[models.py]"]
  node_database[("Relational database")]
  node_email["Email delivery<br/>[service.py]"]
end

node_client(("API client"))
node_ses["AWS SES"]

node_client -->|"sends request"| node_app
node_app -->|"mounts API"| node_v1
node_app -->|"initializes"| node_db_session
node_v1 -->|"authenticates"| node_auth
node_v1 -->|"checks access"| node_permissions
node_v1 -->|"dispatches"| node_catalog
node_v1 -->|"dispatches"| node_telescopes
node_v1 -->|"dispatches"| node_requests
node_v1 -->|"dispatches"| node_schedules
node_v1 -->|"dispatches"| node_observations
node_v1 -->|"dispatches"| node_broker
node_v1 -->|"dispatches"| node_ssa_tools
node_v1 -->|"dispatches"| node_users
node_v1 -->|"dispatches"| node_groups
node_v1 -->|"dispatches"| node_service_accounts
node_auth -->|"queries"| node_db_session
node_catalog -->|"queries"| node_db_session
node_telescopes -->|"queries"| node_db_session
node_requests -->|"reads and writes"| node_db_session
node_schedules -->|"reads and writes"| node_db_session
node_observations -->|"queries"| node_db_session
node_broker -->|"reads and writes"| node_db_session
node_users -->|"uses services"| node_db_session
node_groups -->|"uses services"| node_db_session
node_service_accounts -->|"uses services"| node_db_session
node_db_session -->|"queries"| node_models
node_models -->|"maps records"| node_database
node_email -.->|"sends email"| node_ses

click node_app "https://github.com/nasa-across/across-server/blob/main/across_server/main.py"
click node_v1 "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1"
click node_auth "https://github.com/nasa-across/across-server/tree/main/across_server/auth"
click node_permissions "https://github.com/nasa-across/across-server/blob/main/across_server/auth/strategies.py"
click node_catalog "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observatory"
click node_telescopes "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/telescope"
click node_requests "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observation_request"
click node_schedules "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/schedule"
click node_observations "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observation"
click node_broker "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/broker_alert"
click node_ssa_tools "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/tools"
click node_users "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/user"
click node_groups "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/group"
click node_service_accounts "https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/system_service_account"
click node_db_session "https://github.com/nasa-across/across-server/blob/main/across_server/db/database.py"
click node_models "https://github.com/nasa-across/across-server/blob/main/across_server/db/models.py"
click node_email "https://github.com/nasa-across/across-server/blob/main/across_server/util/email/service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_v1,node_client toneBlue
class node_auth,node_permissions toneAmber
class node_catalog,node_telescopes,node_requests,node_schedules,node_observations,node_broker,node_ssa_tools toneMint
class node_users,node_groups,node_service_accounts toneRose
class node_db_session,node_models,node_database,node_email,node_ses toneIndigo
```

## Components

### API entry

- [FastAPI app](https://github.com/nasa-across/across-server/blob/main/across_server/main.py): `across_server/main.py`
- [Version 1 API](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1): `across_server/routes/v1`

### Identity access

- [Token authentication](https://github.com/nasa-across/across-server/tree/main/across_server/auth): `across_server/auth`
- [Role permissions](https://github.com/nasa-across/across-server/blob/main/across_server/auth/strategies.py): `across_server/auth/strategies.py`

### Science operations

- [Observatory catalog](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observatory): `across_server/routes/v1/observatory`
- [Telescope instruments](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/telescope): `across_server/routes/v1/telescope`
- [Observation requests](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observation_request): `across_server/routes/v1/observation_request`
- [Schedules](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/schedule): `across_server/routes/v1/schedule`
- [Observations](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/observation): `across_server/routes/v1/observation`
- [Broker alerts events](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/broker_alert): `across_server/routes/v1/broker_alert`
- [SSA tools](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/tools): `across_server/routes/v1/tools`

### Accounts administration

- [User accounts](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/user): `across_server/routes/v1/user`
- [Groups and roles](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/group): `across_server/routes/v1/group`
- [Service accounts](https://github.com/nasa-across/across-server/tree/main/across_server/routes/v1/system_service_account): `across_server/routes/v1/system_service_account`

### Shared infrastructure

- [DB sessions](https://github.com/nasa-across/across-server/blob/main/across_server/db/database.py): `across_server/db/database.py`
- [SQLAlchemy models](https://github.com/nasa-across/across-server/blob/main/across_server/db/models.py): `across_server/db/models.py`
- **Relational database**
- [Email delivery](https://github.com/nasa-across/across-server/blob/main/across_server/util/email/service.py): `across_server/util/email/service.py`

### Other components

- **API client**
- **AWS SES**

## Connections

- API client → FastAPI app: sends request
- FastAPI app → Version 1 API: mounts API
- FastAPI app → DB sessions: initializes
- Version 1 API → Token authentication: authenticates
- Version 1 API → Role permissions: checks access
- Version 1 API → Observatory catalog: dispatches
- Version 1 API → Telescope instruments: dispatches
- Version 1 API → Observation requests: dispatches
- Version 1 API → Schedules: dispatches
- Version 1 API → Observations: dispatches
- Version 1 API → Broker alerts events: dispatches
- Version 1 API → SSA tools: dispatches
- Version 1 API → User accounts: dispatches
- Version 1 API → Groups and roles: dispatches
- Version 1 API → Service accounts: dispatches
- Token authentication → DB sessions: queries
- Observatory catalog → DB sessions: queries
- Telescope instruments → DB sessions: queries
- Observation requests → DB sessions: reads and writes
- Schedules → DB sessions: reads and writes
- Observations → DB sessions: queries
- Broker alerts events → DB sessions: reads and writes
- User accounts → DB sessions: uses services
- Groups and roles → DB sessions: uses services
- Service accounts → DB sessions: uses services
- DB sessions → SQLAlchemy models: queries
- SQLAlchemy models → Relational database: maps records
- Email delivery → AWS SES: sends email