# flatcar/nebraska architecture

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

- Interactive diagram: https://gitdiagram.com/flatcar/nebraska
- Repository: https://github.com/flatcar/nebraska

## Overview

Nebraska manages Omaha-protocol update rollouts, with Flatcar-focused update and payload capabilities. Operators configure applications, channels, packages, and instance groups in the web console; instances request updates through Omaha, while the backend serves and records rollout activity. The sampled startup and application-handler code establishes the server, service, and persistence wiring. The README documents broader rollout, statistics, activity, and Flatcar capabilities; unsampled implementation links are omitted or marked unverified.

Main entry points: [`backend/pkg/handler/handler.go`](https://github.com/flatcar/nebraska/blob/main/backend/pkg/handler/handler.go) (HTTP handlers), [`frontend/src/components/Main.tsx`](https://github.com/flatcar/nebraska/blob/main/frontend/src/components/Main.tsx) (Console routes), [`backend/pkg/api/admin`](https://github.com/flatcar/nebraska/tree/main/backend/pkg/api/admin) (Admin service), [`backend/cmd/nebraska/main.go`](https://github.com/flatcar/nebraska/blob/main/backend/cmd/nebraska/main.go) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Runtime entry"]
  node_main["Application startup<br/>[main.go]"]
  node_server["HTTP server<br/>[server.go]"]
  node_handler["HTTP handlers<br/>[handler.go]"]
  node_apphandler["Application routes<br/>[app.go]"]
end

subgraph group_domain["Rollout services"]
  node_admin["Admin service"]
  node_runtime["Runtime service<br/>[service.go]"]
end

subgraph group_persistence["Persistence"]
  node_database[("Application database<br/>[conn.go]")]
  node_dbreads["Read queries<br/>[applications.go]"]
end

subgraph group_console["Web console"]
  node_frontend["Console bootstrap<br/>[App.tsx]"]
  node_mainview["Console routes<br/>[Main.tsx]"]
  node_auth["Authentication flow<br/>[auth.ts]"]
  node_api["Console API client<br/>[API.ts]"]
  node_apps["App management"]
  node_groups["Group management"]
  node_instances["Instance monitoring"]
  node_activity["Activity timeline"]
  node_packages["Package management"]
end

subgraph group_updates["Update delivery"]
  node_omaha["Omaha protocol<br/>[omaha.go]"]
  node_syncer["Update syncer<br/>[syncer.go]"]
  node_updater["Update handlers"]
end

node_operator(("Operator"))
node_instance(("Omaha instance"))

node_operator -->|"manages rollouts"| node_frontend
node_instance -->|"requests updates"| node_handler
node_main -->|"starts"| node_server
node_main -->|"constructs"| node_admin
node_main -->|"constructs"| node_runtime
node_main -->|"starts optionally"| node_syncer
node_server -->|"registers routes"| node_handler
node_handler -->|"invokes"| node_admin
node_handler -->|"invokes"| node_runtime
node_handler -->|"constructs handler"| node_omaha
node_handler -->|"implements routes"| node_apphandler
node_apphandler -->|"writes app data"| node_admin
node_apphandler -->|"reads app data"| node_dbreads
node_admin -->|"writes records"| node_database
node_dbreads -->|"queries records"| node_database
node_runtime -->|"uses queries"| node_dbreads
node_frontend -->|"loads configuration"| node_api
node_frontend -->|"renders routes"| node_mainview
node_mainview -->|"guards routes"| node_auth
node_mainview -->|"routes to"| node_apps
node_mainview -->|"routes to"| node_groups
node_mainview -->|"routes to"| node_instances
node_frontend -.->|"requests data"| node_api
node_api -.->|"calls endpoints"| node_apphandler
node_syncer -->|"uses admin service"| node_admin
node_omaha -.->|"serves update flow"| node_runtime
node_updater -.->|"delivers update response"| node_instance

click node_main "https://github.com/flatcar/nebraska/blob/main/backend/cmd/nebraska/main.go"
click node_server "https://github.com/flatcar/nebraska/blob/main/backend/pkg/server/server.go"
click node_handler "https://github.com/flatcar/nebraska/blob/main/backend/pkg/handler/handler.go"
click node_admin "https://github.com/flatcar/nebraska/tree/main/backend/pkg/api/admin"
click node_runtime "https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/runtime/service.go"
click node_omaha "https://github.com/flatcar/nebraska/blob/main/backend/pkg/omaha/omaha.go"
click node_syncer "https://github.com/flatcar/nebraska/blob/main/backend/pkg/syncer/syncer.go"
click node_updater "https://github.com/flatcar/nebraska/tree/main/updater"
click node_database "https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/internal/dbconn/conn.go"
click node_dbreads "https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/internal/dbreads/applications.go"
click node_apphandler "https://github.com/flatcar/nebraska/blob/main/backend/pkg/handler/app.go"
click node_frontend "https://github.com/flatcar/nebraska/blob/main/frontend/src/App.tsx"
click node_mainview "https://github.com/flatcar/nebraska/blob/main/frontend/src/components/Main.tsx"
click node_auth "https://github.com/flatcar/nebraska/blob/main/frontend/src/utils/auth.ts"
click node_api "https://github.com/flatcar/nebraska/blob/main/frontend/src/api/API.ts"
click node_apps "https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Applications"
click node_groups "https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Groups"
click node_instances "https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Instances"
click node_activity "https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Activity"
click node_packages "https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Packages"

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_main,node_server,node_handler,node_apphandler toneBlue
class node_admin,node_runtime toneAmber
class node_database,node_dbreads toneMint
class node_frontend,node_mainview,node_auth,node_api,node_apps,node_groups,node_instances,node_activity,node_packages toneRose
class node_omaha,node_syncer,node_updater,node_operator,node_instance toneIndigo
```

## Components

### Runtime entry

- [Application startup](https://github.com/flatcar/nebraska/blob/main/backend/cmd/nebraska/main.go): `backend/cmd/nebraska/main.go`
- [HTTP server](https://github.com/flatcar/nebraska/blob/main/backend/pkg/server/server.go): `backend/pkg/server/server.go`
- [HTTP handlers](https://github.com/flatcar/nebraska/blob/main/backend/pkg/handler/handler.go): `backend/pkg/handler/handler.go`
- [Application routes](https://github.com/flatcar/nebraska/blob/main/backend/pkg/handler/app.go): `backend/pkg/handler/app.go`

### Rollout services

- [Admin service](https://github.com/flatcar/nebraska/tree/main/backend/pkg/api/admin): `backend/pkg/api/admin`
- [Runtime service](https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/runtime/service.go): `backend/pkg/api/runtime/service.go`

### Persistence

- [Application database](https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/internal/dbconn/conn.go): `backend/pkg/api/internal/dbconn/conn.go`
- [Read queries](https://github.com/flatcar/nebraska/blob/main/backend/pkg/api/internal/dbreads/applications.go): `backend/pkg/api/internal/dbreads/applications.go`

### Web console

- [Console bootstrap](https://github.com/flatcar/nebraska/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Console routes](https://github.com/flatcar/nebraska/blob/main/frontend/src/components/Main.tsx): `frontend/src/components/Main.tsx`
- [Authentication flow](https://github.com/flatcar/nebraska/blob/main/frontend/src/utils/auth.ts): `frontend/src/utils/auth.ts`
- [Console API client](https://github.com/flatcar/nebraska/blob/main/frontend/src/api/API.ts): `frontend/src/api/API.ts`
- [App management](https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Applications): `frontend/src/components/Applications`
- [Group management](https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Groups): `frontend/src/components/Groups`
- [Instance monitoring](https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Instances): `frontend/src/components/Instances`
- [Activity timeline](https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Activity): `frontend/src/components/Activity`
- [Package management](https://github.com/flatcar/nebraska/tree/main/frontend/src/components/Packages): `frontend/src/components/Packages`

### Update delivery

- [Omaha protocol](https://github.com/flatcar/nebraska/blob/main/backend/pkg/omaha/omaha.go): `backend/pkg/omaha/omaha.go`
- [Update syncer](https://github.com/flatcar/nebraska/blob/main/backend/pkg/syncer/syncer.go): `backend/pkg/syncer/syncer.go`
- [Update handlers](https://github.com/flatcar/nebraska/tree/main/updater): `updater`

### Other components

- **Operator**
- **Omaha instance**

## Connections

- Operator → Console bootstrap: manages rollouts (evidence: `README.md`)
- Omaha instance → HTTP handlers: requests updates (evidence: `README.md`)
- Application startup → HTTP server: starts (evidence: `backend/cmd/nebraska/main.go`)
- Application startup → Admin service: constructs (evidence: `backend/cmd/nebraska/main.go`)
- Application startup → Runtime service: constructs (evidence: `backend/cmd/nebraska/main.go`)
- Application startup → Update syncer: starts optionally (evidence: `backend/cmd/nebraska/main.go`)
- HTTP server → HTTP handlers: registers routes (evidence: `backend/pkg/server/server.go`)
- HTTP handlers → Admin service: invokes (evidence: `backend/pkg/handler/handler.go`)
- HTTP handlers → Runtime service: invokes (evidence: `backend/pkg/handler/handler.go`)
- HTTP handlers → Omaha protocol: constructs handler (evidence: `backend/pkg/handler/handler.go`)
- HTTP handlers → Application routes: implements routes (evidence: `backend/pkg/handler/handler.go`)
- Application routes → Admin service: writes app data (evidence: `backend/pkg/handler/app.go`)
- Application routes → Read queries: reads app data (evidence: `backend/pkg/handler/app.go`)
- Admin service → Application database: writes records (evidence: `backend/pkg/api/admin/applications.go`)
- Read queries → Application database: queries records (evidence: `backend/pkg/api/internal/dbreads/applications.go`)
- Runtime service → Read queries: uses queries (evidence: `backend/pkg/api/runtime/service.go`)
- Console bootstrap → Console API client: loads configuration (evidence: `frontend/src/App.tsx`)
- Console bootstrap → Console routes: renders routes (evidence: `frontend/src/App.tsx`)
- Console routes → Authentication flow: guards routes (evidence: `frontend/src/components/Main.tsx`)
- Console routes → App management: routes to (evidence: `frontend/src/components/Main.tsx`)
- Console routes → Group management: routes to (evidence: `frontend/src/components/Main.tsx`)
- Console routes → Instance monitoring: routes to (evidence: `frontend/src/components/Main.tsx`)
- Console bootstrap → Console API client: requests data (evidence: `frontend/src/App.tsx`)
- Console API client → Application routes: calls endpoints
- Update syncer → Admin service: uses admin service
- Omaha protocol → Runtime service: serves update flow
- Update handlers → Omaha instance: delivers update response
