# emad60/nexusops architecture

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

- Interactive diagram: https://gitdiagram.com/emad60/nexusops
- Repository: https://github.com/emad60/nexusops

## Overview

NexusOps is a self-hosted infrastructure control plane: users manage a tenant-scoped fleet through a React SPA and FastAPI API, while enrolled agents report state and pull approved operations. Its operational loop spans telemetry, monitoring and incidents, notification, deployments, and HTTP domain routing; certificate issuance exists, but delivery or installation on nodes does not. Celery workers execute scheduled and queued work, with PostgreSQL for durable state and Redis for queues and event fan-out. Edges are limited to relationships documented in the README or shown in excerpts; several unsampled feature internals are represented by their enclosing source directories.

Main entry points: [`backend/app/main.py`](https://github.com/emad60/nexusops/blob/main/backend/app/main.py) (REST API), [`backend/app/tasks/celery_app.py`](https://github.com/emad60/nexusops/blob/main/backend/app/tasks/celery_app.py) (Celery workers), [`backend/app/api/v1/agent.py`](https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/agent.py) (Server and operations), [`backend/app/api/v1/routes.py`](https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/routes.py) (Domain and route API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_spa["React SPA<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_websocket["WebSocket hub<br/>[hub.py]"]
end

subgraph group_control["API and tenancy"]
  node_api["REST API<br/>[main.py]"]
  node_auth_tenancy["Auth and tenancy<br/>[deps.py]"]
  node_data_model["Tenant data model<br/>[base.py]"]
end

subgraph group_fleet["Fleet operations"]
  node_agent["Node agent<br/>[nexusops_agent.py]"]
  node_server_ops["Server and operations<br/>[agent.py]"]
  node_monitoring["Monitoring and incidents<br/>[monitor_service.py]"]
  node_notifications["Notifications"]
end

subgraph group_delivery["Delivery and routing"]
  node_domain_api["Domain and route API<br/>[routes.py]"]
  node_deployment["Deployment engine"]
  node_domain_service["Domain verification<br/>[domain_service.py]"]
  node_route_service["Route configuration<br/>[proxy_service.py]"]
  node_cert_issuance["Certificate issuance"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_event_bus["Event bus<br/>[event_bus.py]"]
  node_celery["Celery workers<br/>[celery_app.py]"]
  node_infra{{"Managed infrastructure"}}
end

node_user(("Operator"))
node_mail{{"Email service"}}

node_user -->|"uses"| node_spa
node_spa -->|"calls"| node_api_client
node_api_client -.->|"requests"| node_api
node_api -->|"resolves identity"| node_auth_tenancy
node_auth_tenancy -.->|"checks membership"| node_postgres
node_api -.->|"reads and writes"| node_postgres
node_api -.->|"uses"| node_redis
node_api -->|"routes requests"| node_domain_api
node_domain_api -->|"calls"| node_route_service
node_domain_api -->|"calls"| node_domain_service
node_agent -->|"reports heartbeat"| node_server_ops
node_server_ops -->|"returns pending work"| node_agent
node_server_ops -.->|"stores fleet state"| node_postgres
node_celery -->|"consumes queues"| node_redis
node_celery -->|"reads and writes"| node_postgres
node_celery -.->|"runs checks"| node_monitoring
node_monitoring -.->|"raises and notifies"| node_notifications
node_notifications -.->|"sends email"| node_mail
node_celery -->|"executes jobs"| node_deployment
node_deployment -->|"streams logs"| node_redis
node_domain_service -.->|"coordinates routes"| node_route_service
node_route_service -->|"ships nginx operations"| node_agent
node_domain_service -->|"verifies DNS"| node_infra
node_cert_issuance -.->|"checks DNS propagation"| node_infra
node_api -.->|"publishes events"| node_event_bus
node_event_bus -->|"fans out events"| node_redis
node_redis -->|"feeds events"| node_websocket
node_websocket -->|"streams updates"| node_spa
node_data_model -.->|"maps records"| node_postgres

click node_spa "https://github.com/emad60/nexusops/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/emad60/nexusops/blob/main/frontend/src/api/client.ts"
click node_agent "https://github.com/emad60/nexusops/blob/main/agent/nexusops_agent.py"
click node_api "https://github.com/emad60/nexusops/blob/main/backend/app/main.py"
click node_auth_tenancy "https://github.com/emad60/nexusops/blob/main/backend/app/api/deps.py"
click node_domain_api "https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/routes.py"
click node_data_model "https://github.com/emad60/nexusops/blob/main/backend/app/models/base.py"
click node_event_bus "https://github.com/emad60/nexusops/blob/main/backend/app/services/event_bus.py"
click node_websocket "https://github.com/emad60/nexusops/blob/main/backend/app/ws/hub.py"
click node_celery "https://github.com/emad60/nexusops/blob/main/backend/app/tasks/celery_app.py"
click node_server_ops "https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/agent.py"
click node_monitoring "https://github.com/emad60/nexusops/blob/main/backend/app/services/monitor_service.py"
click node_notifications "https://github.com/emad60/nexusops/blob/main/backend/app/services/notification_service.py"
click node_deployment "https://github.com/emad60/nexusops/blob/main/backend/app/services/deployment_engine.py"
click node_domain_service "https://github.com/emad60/nexusops/blob/main/backend/app/services/domain_service.py"
click node_route_service "https://github.com/emad60/nexusops/blob/main/backend/app/services/proxy_service.py"
click node_cert_issuance "https://github.com/emad60/nexusops/blob/main/backend/app/services/certificate_issuance.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_spa,node_api_client,node_websocket toneBlue
class node_api,node_auth_tenancy,node_data_model toneAmber
class node_agent,node_server_ops,node_monitoring,node_notifications toneMint
class node_domain_api,node_deployment,node_domain_service,node_route_service,node_cert_issuance toneRose
class node_postgres,node_redis,node_event_bus,node_celery,node_infra,node_user,node_mail toneIndigo
```

## Components

### User experience

- [React SPA](https://github.com/emad60/nexusops/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/emad60/nexusops/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [WebSocket hub](https://github.com/emad60/nexusops/blob/main/backend/app/ws/hub.py): `backend/app/ws/hub.py`

### API and tenancy

- [REST API](https://github.com/emad60/nexusops/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth and tenancy](https://github.com/emad60/nexusops/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Tenant data model](https://github.com/emad60/nexusops/blob/main/backend/app/models/base.py): `backend/app/models/base.py`

### Fleet operations

- [Node agent](https://github.com/emad60/nexusops/blob/main/agent/nexusops_agent.py): `agent/nexusops_agent.py`
- [Server and operations](https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/agent.py): `backend/app/api/v1/agent.py`
- [Monitoring and incidents](https://github.com/emad60/nexusops/blob/main/backend/app/services/monitor_service.py): `backend/app/services/monitor_service.py`
- [Notifications](https://github.com/emad60/nexusops/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`

### Delivery and routing

- [Domain and route API](https://github.com/emad60/nexusops/blob/main/backend/app/api/v1/routes.py): `backend/app/api/v1/routes.py`
- [Deployment engine](https://github.com/emad60/nexusops/blob/main/backend/app/services/deployment_engine.py): `backend/app/services/deployment_engine.py`
- [Domain verification](https://github.com/emad60/nexusops/blob/main/backend/app/services/domain_service.py): `backend/app/services/domain_service.py`
- [Route configuration](https://github.com/emad60/nexusops/blob/main/backend/app/services/proxy_service.py): `backend/app/services/proxy_service.py`
- [Certificate issuance](https://github.com/emad60/nexusops/blob/main/backend/app/services/certificate_issuance.py): `backend/app/services/certificate_issuance.py`

### Runtime infrastructure

- **PostgreSQL**
- **Redis**
- [Event bus](https://github.com/emad60/nexusops/blob/main/backend/app/services/event_bus.py): `backend/app/services/event_bus.py`
- [Celery workers](https://github.com/emad60/nexusops/blob/main/backend/app/tasks/celery_app.py): `backend/app/tasks/celery_app.py`
- **Managed infrastructure**

### Other components

- **Operator**
- **Email service**

## Connections

- Operator → React SPA: uses
- React SPA → API client: calls (evidence: `frontend/src/App.tsx`)
- API client → REST API: requests
- REST API → Auth and tenancy: resolves identity (evidence: `backend/app/api/deps.py`)
- Auth and tenancy → PostgreSQL: checks membership
- REST API → PostgreSQL: reads and writes
- REST API → Redis: uses
- REST API → Domain and route API: routes requests (evidence: `backend/app/main.py`)
- Domain and route API → Route configuration: calls (evidence: `backend/app/api/v1/routes.py`)
- Domain and route API → Domain verification: calls (evidence: `backend/app/api/v1/routes.py`)
- Node agent → Server and operations: reports heartbeat
- Server and operations → Node agent: returns pending work
- Server and operations → PostgreSQL: stores fleet state
- Celery workers → Redis: consumes queues
- Celery workers → PostgreSQL: reads and writes
- Celery workers → Monitoring and incidents: runs checks
- Monitoring and incidents → Notifications: raises and notifies
- Notifications → Email service: sends email
- Celery workers → Deployment engine: executes jobs (evidence: `backend/app/services/deployment_engine.py`)
- Deployment engine → Redis: streams logs (evidence: `backend/app/services/deployment_engine.py`)
- Domain verification → Route configuration: coordinates routes (evidence: `backend/app/tasks/domain_routing.py`)
- Route configuration → Node agent: ships nginx operations
- Domain verification → Managed infrastructure: verifies DNS
- Certificate issuance → Managed infrastructure: checks DNS propagation
- REST API → Event bus: publishes events
- Event bus → Redis: fans out events (evidence: `backend/app/services/event_bus.py`)
- Redis → WebSocket hub: feeds events
- WebSocket hub → React SPA: streams updates
- Tenant data model → PostgreSQL: maps records
