# aarnphm/scemas-platform architecture

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

- Interactive diagram: https://gitdiagram.com/aarnphm/scemas-platform
- Repository: https://github.com/aarnphm/scemas-platform

## Overview

1. **System shape**
   This repository is a monorepo for a smart-city environmental monitoring and alerting platform. The architecture is split into a Rust backend/engine, a TypeScript web platform, and a desktop client. The codebase is explicitly organized around PAC-style presentation agents and server-side controllers.

2. **Core runtime boundary**
   The main backend logic lives in the Rust workspace under `crates/`. It contains the shared domain model, telemetry validation, alert evaluation, and an internal Axum-based server. This Rust layer is the system’s control and processing boundary; the web and desktop UIs sit on top of it.

3. **Domain model and shared types**
   `scemas-core` holds the shared entities, config, lifecycle primitives, region catalog, and error types used across the Rust workspace. On the TypeScript side, `packages/types` and `packages/db` provide shared API schemas and database schema definitions so the UI and server can agree on data shapes.

4. **Telemetry ingestion pipeline**
   `scemas-telemetry` implements the telemetry controller as a pipe-and-filter pipeline: incoming readings are validated, range-checked, and timestamp-checked before they are accepted. This is the system’s first data gate, and it feeds downstream storage and alerting only after validation succeeds.

5. **Alerting subsystem**
   `scemas-alerting` is the alert controller and is organized as a blackboard system. Evaluator, lifecycle, and dispatcher modules coordinate through shared state to create, update, acknowledge, resolve, and dispatch alerts. This subsystem also drives outbound webhooks for alert subscriptions.

6. **Internal Rust API**
   `scemas-server` exposes internal server-to-server routes on the Rust side. These routes handle signup/login, alert rule changes, alert actions, telemetry ingest, and health checks. This server is the backend service boundary used by the dashboard, seed scripts, and other trusted clients.

7. **Web platform and PAC agents**
   `packages/dashboard` is the main Next.js 15 application and implements the three PAC presentation agents: operator, admin, and public. Route groups enforce the agent separation, while middleware and auth helpers enforce role-based access. The operator views emphasize live monitoring and alert handling; admin views focus on users, rules, audit, and health; public views expose abstracted AQI data.

8. **Data distribution and request aggregation**
   The dashboard’s server layer contains the Data Distribution Manager and tRPC routers. These modules aggregate and transform data for the three agents, mediate access to internal Rust services, and provide the browser-facing API surface at `/api/trpc` and `/api/v1/*`. This is the main presentation-to-control integration point for the web app.

9. **Auth, access control, and public API**
   Authentication is handled through OAuth/session logic in the dashboard server and Rust internal routes, with role-based enforcement tied to the PAC agents. The public API is intentionally narrower than the authenticated operator/admin surfaces; it exposes only aggregated zone/AQI information and strips sensitive detail.

10. **Database as shared persistence layer**
   PostgreSQL is the shared persistence layer across the platform. `packages/db` owns the Drizzle schema and migrations, while the Rust engine uses SQLx against the same database. Several scripts support user seeding and schema synchronization, showing that the DB schema is a central integration contract.

11. **Desktop product boundary**
   The desktop experience is split between a Rust Tauri host (`crates/scemas-desktop`) and a Vite/React frontend (`packages/desktop`). The desktop host can run with embedded PostgreSQL, manage local runtime concerns, and sync with the backend. It mirrors much of the web app’s operator/admin/public surfaces while staying a separate deployment target.

12. **Deployment and hosting**
   The web platform is designed for Bun/Next.js deployment via OpenNext/Cloudflare Workers, while the Rust engine is a separate service/runtime. CI workflows build both web and desktop artifacts, and the desktop build bundles PostgreSQL binaries for offline/local execution. This creates two deployment modes: cloud-hosted web and packaged desktop.

13. **Seed, demo, and simulation tooling**
   The repo includes sample sensor datasets, a seed CLI, and helper scripts for generating monitoring data and webhook traffic. These are not just utilities; they are part of the system’s data flow for demos, testing, and alert-trigger validation.

14. **Documentation as architecture source**
   The `docs/diagrams` directory is the authoritative design reference, with UML class and sequence diagrams covering login, rule creation, alert acknowledgement, telemetry handling, and data distribution. If you are drawing the architecture, the repository’s own documentation treats those diagrams as the source of truth for behavior and boundaries.

Main entry points: [`crates/scemas-server/src/routes.rs`](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-server/src/routes.rs) (Internal API), [`packages/dashboard/app/layout.tsx`](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/app/layout.tsx) (Dashboard app), [`crates/scemas-desktop/src/main.rs`](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-desktop/src/main.rs) (Desktop host), [`packages/db/src/schema.ts`](https://github.com/aarnphm/scemas-platform/blob/main/packages/db/src/schema.ts) (DB schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rust["Rust backend"]
  node_core["Core model<br/>Rust domain<br/>[lib.rs]"]
  node_telemetry["Telemetry gate<br/>Rust pipeline<br/>[controller.rs]"]
  node_alerting["Alert engine<br/>Rust blackboard<br/>[controller.rs]"]
  node_server["Internal API<br/>Rust Axum<br/>[routes.rs]"]
  node_cli["Seed CLI<br/>Rust command<br/>[main.rs]"]
end

subgraph group_web["Web platform"]
  node_dashboard["Dashboard app<br/>Next.js app<br/>[layout.tsx]"]
  node_ddm["Data manager<br/>Web server"]
  node_trpc["tRPC layer<br/>Web API<br/>[router.ts]"]
  node_auth["Auth layer<br/>Web auth<br/>[oauth.ts]"]
  node_publicapi["Public API<br/>Web facade<br/>[public-api.ts]"]
  node_worker["Edge worker<br/>Cloudflare worker<br/>[worker.ts]"]
end

subgraph group_desktop["Desktop client"]
  node_desktophost["Desktop host<br/>Tauri host<br/>[main.rs]"]
  node_desktopui["Desktop UI<br/>Vite React<br/>[main.tsx]"]
  node_desktopsync["Desktop sync<br/>Desktop bridge<br/>[sync.rs]"]
end

subgraph group_shared["Shared contracts"]
  node_dbschema[("DB schema<br/>Drizzle schema<br/>[schema.ts]")]
  node_types["API types<br/>TS contracts<br/>[index.ts]"]
end

subgraph group_ops["Tooling & docs"]
  node_docs["Architecture docs<br/>Design refs<br/>[class_diagram.puml]"]
  node_scripts["Ops scripts<br/>Tooling<br/>[start-scemas.sh]"]
end

node_core -->|"shared model"| node_telemetry
node_core -->|"shared model"| node_alerting
node_core -->|"shared model"| node_server
node_telemetry -->|"ingest"| node_server
node_alerting -->|"actions"| node_server
node_server -->|"persistence"| node_dbschema
node_cli -->|"seed data"| node_dbschema
node_dashboard -->|"protects"| node_auth
node_dashboard -->|"delegates"| node_ddm
node_ddm -->|"feeds"| node_trpc
node_trpc -->|"backend calls"| node_server
node_publicapi -->|"public fetch"| node_server
node_auth -->|"login and oauth"| node_server
node_dashboard -->|"contracts"| node_types
node_dashboard -->|"shared data"| node_dbschema
node_worker -->|"deploys"| node_dashboard
node_desktophost -->|"shells"| node_desktopui
node_desktophost -->|"syncs"| node_desktopsync
node_desktophost -->|"local postgres"| node_dbschema
node_docs -.->|"specifies"| node_server
node_docs -.->|"specifies"| node_telemetry
node_docs -.->|"specifies"| node_alerting
node_scripts -->|"drives"| node_cli
node_scripts -->|"packages"| node_desktophost

click node_core "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-core/src/lib.rs"
click node_telemetry "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-telemetry/src/controller.rs"
click node_alerting "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-alerting/src/controller.rs"
click node_server "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-server/src/routes.rs"
click node_cli "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-cli/src/main.rs"
click node_dashboard "https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/app/layout.tsx"
click node_ddm "https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/data-distribution-manager.ts"
click node_trpc "https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/router.ts"
click node_auth "https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/oauth.ts"
click node_publicapi "https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/public-api.ts"
click node_worker "https://github.com/aarnphm/scemas-platform/blob/main/packages/api/src/worker.ts"
click node_dbschema "https://github.com/aarnphm/scemas-platform/blob/main/packages/db/src/schema.ts"
click node_types "https://github.com/aarnphm/scemas-platform/blob/main/packages/types/src/index.ts"
click node_desktophost "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-desktop/src/main.rs"
click node_desktopui "https://github.com/aarnphm/scemas-platform/blob/main/packages/desktop/src/main.tsx"
click node_desktopsync "https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-desktop/src/sync.rs"
click node_docs "https://github.com/aarnphm/scemas-platform/blob/main/docs/diagrams/class_diagram.puml"
click node_scripts "https://github.com/aarnphm/scemas-platform/blob/main/scripts/start-scemas.sh"

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_core,node_telemetry,node_alerting,node_server,node_cli toneBlue
class node_dashboard,node_ddm,node_trpc,node_auth,node_publicapi,node_worker toneAmber
class node_desktophost,node_desktopui,node_desktopsync toneMint
class node_dbschema,node_types toneRose
class node_docs,node_scripts toneIndigo
```

## Components

### Rust backend

Core control and processing boundary in the Rust workspace.

- [Core model](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-core/src/lib.rs): Rust domain · Shared entities, config, lifecycle, regions, and errors for the Rust workspace. · `crates/scemas-core/src/lib.rs`
- [Telemetry gate](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-telemetry/src/controller.rs): Rust pipeline · Validates, range-checks, and timestamp-checks incoming readings before acceptance. · `crates/scemas-telemetry/src/controller.rs`
- [Alert engine](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-alerting/src/controller.rs): Rust blackboard · Coordinates alert evaluation, lifecycle, and dispatch over shared state. · `crates/scemas-alerting/src/controller.rs`
- [Internal API](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-server/src/routes.rs): Rust Axum · Internal service boundary for auth, telemetry ingest, alert actions, and health routes. · `crates/scemas-server/src/routes.rs`
- [Seed CLI](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-cli/src/main.rs): Rust command · Command-line entry for reload and database seeding workflows. · `crates/scemas-cli/src/main.rs`

### Web platform

Next.js dashboard plus its server-side integration layer.

- [Dashboard app](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/app/layout.tsx): Next.js app · Main web application with PAC presentation agents for operator, admin, and public views. · `packages/dashboard/app/layout.tsx`
- [Data manager](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/data-distribution-manager.ts): Web server · Aggregates and transforms backend data for the dashboard agents and APIs. · `packages/dashboard/server/data-distribution-manager.ts`
- [tRPC layer](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/router.ts): Web API · Browser-facing API surface and router composition for dashboard requests. · `packages/dashboard/server/router.ts`
- [Auth layer](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/oauth.ts): Web auth · OAuth, sessions, middleware, and role checks for PAC separation. · `packages/dashboard/server/oauth.ts`
- [Public API](https://github.com/aarnphm/scemas-platform/blob/main/packages/dashboard/server/public-api.ts): Web facade · Narrow public endpoints that expose aggregated zone and AQI data. · `packages/dashboard/server/public-api.ts`
- [Edge worker](https://github.com/aarnphm/scemas-platform/blob/main/packages/api/src/worker.ts): Cloudflare worker · Cloud deployment entry for the web platform. · `packages/api/src/worker.ts`

### Desktop client

Tauri host and React desktop front end.

- [Desktop host](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-desktop/src/main.rs): Tauri host · Rust desktop shell with local runtime, sync, and command bridge. · `crates/scemas-desktop/src/main.rs`
- [Desktop UI](https://github.com/aarnphm/scemas-platform/blob/main/packages/desktop/src/main.tsx): Vite React · Desktop front end mirroring operator, admin, and public surfaces. · `packages/desktop/src/main.tsx`
- [Desktop sync](https://github.com/aarnphm/scemas-platform/blob/main/crates/scemas-desktop/src/sync.rs): Desktop bridge · Local PostgreSQL, remote sync, and command/query coordination for desktop mode. · `crates/scemas-desktop/src/sync.rs`

### Shared contracts

Cross-runtime schemas and persistence definitions.

- [DB schema](https://github.com/aarnphm/scemas-platform/blob/main/packages/db/src/schema.ts): Drizzle schema · PostgreSQL schema and migrations shared by web, desktop, and backend integration. · `packages/db/src/schema.ts`
- [API types](https://github.com/aarnphm/scemas-platform/blob/main/packages/types/src/index.ts): TS contracts · Shared API schemas and transport types used across the TypeScript workspace. · `packages/types/src/index.ts`

### Tooling & docs

Build, seed, deployment, and architectural documentation.

- [Architecture docs](https://github.com/aarnphm/scemas-platform/blob/main/docs/diagrams/class_diagram.puml): Design refs · UML diagrams and runbooks that define the intended controller behavior. · `docs/diagrams/class_diagram.puml`
- [Ops scripts](https://github.com/aarnphm/scemas-platform/blob/main/scripts/start-scemas.sh): Tooling · Seed, monitoring, webhook, and packaging scripts used in demos and deployment. · `scripts/start-scemas.sh`

## Connections

- Core model → Telemetry gate: shared model · Telemetry validation relies on shared entities and region/config types.
- Core model → Alert engine: shared model · Alert evaluation and lifecycle use the same domain primitives.
- Core model → Internal API: shared model · Internal routes work over the common Rust domain and errors.
- Telemetry gate → Internal API: ingest · Validated readings are handed to the internal server boundary.
- Alert engine → Internal API: actions · Alert state changes and dispatch flows are exposed through server routes.
- Internal API → DB schema: persistence · The internal API reads and writes the shared PostgreSQL contract.
- Seed CLI → DB schema: seed data · Seed and reload commands target the shared database schema.
- Dashboard app → Auth layer: protects · The app shell enforces agent separation and access control.
- Dashboard app → Data manager: delegates · Presentation routes rely on the data manager for aggregation.
- Data manager → tRPC layer: feeds · Aggregated data is surfaced through the dashboard API layer.
- tRPC layer → Internal API: backend calls · tRPC and API routes mediate access to internal Rust services.
- Public API → Internal API: public fetch · Public endpoints forward to restricted backend data and rules.
- Auth layer → Internal API: login and oauth · Session and OAuth flows integrate with trusted Rust routes.
- Dashboard app → API types: contracts · The web app uses shared API schemas and shapes.
- Dashboard app → DB schema: shared data · Dashboard server components and scripts assume the central DB contract.
- Edge worker → Dashboard app: deploys · The edge worker hosts the web platform in cloud deployment.
- Desktop host → Desktop UI: shells · The Tauri runtime wraps the React desktop front end.
- Desktop host → Desktop sync: syncs · Local runtime concerns and backend synchronization are handled here.
- Desktop host → DB schema: local postgres · Desktop mode can run against an embedded PostgreSQL instance.
- Architecture docs → Internal API: specifies · Sequence and class diagrams document server and controller behavior.
- Architecture docs → Telemetry gate: specifies · Telemetry controller diagrams describe validation and ingest flow.
- Architecture docs → Alert engine: specifies · Alerting diagrams define blackboard coordination and actions.
- Ops scripts → Seed CLI: drives · Operational scripts use seed and reload workflows.
- Ops scripts → Desktop host: packages · Build scripts bundle desktop dependencies including PostgreSQL binaries.
