How aarnphm/scemas-platform works
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: routes.rs Internal API · layout.tsx Dashboard app · main.rs Desktop host · schema.ts DB schema
Components 18
Rust backend
Core control and processing boundary in the Rust workspace.
- Core model · Shared entities, config, lifecycle, regions, and errors for the Rust workspace.
crates/scemas-core/src/lib.rs - Telemetry gate · Validates, range-checks, and timestamp-checks incoming readings before acceptance.
crates/scemas-telemetry/src/controller.rs - Alert engine · Coordinates alert evaluation, lifecycle, and dispatch over shared state.
crates/scemas-alerting/src/controller.rs - Internal API · Internal service boundary for auth, telemetry ingest, alert actions, and health routes.
crates/scemas-server/src/routes.rs - Seed CLI · 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 · Main web application with PAC presentation agents for operator, admin, and public views.
packages/dashboard/app/layout.tsx - Data manager · Aggregates and transforms backend data for the dashboard agents and APIs.
packages/dashboard/server/data-distribution-manager.ts - tRPC layer · Browser-facing API surface and router composition for dashboard requests.
packages/dashboard/server/router.ts - Auth layer · OAuth, sessions, middleware, and role checks for PAC separation.
packages/dashboard/server/oauth.ts - Public API · Narrow public endpoints that expose aggregated zone and AQI data.
packages/dashboard/server/public-api.ts - Edge worker · Cloud deployment entry for the web platform.
packages/api/src/worker.ts
Desktop client
Tauri host and React desktop front end.
- Desktop host · Rust desktop shell with local runtime, sync, and command bridge.
crates/scemas-desktop/src/main.rs - Desktop UI · Desktop front end mirroring operator, admin, and public surfaces.
packages/desktop/src/main.tsx - Desktop sync · 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.
Tooling & docs
Build, seed, deployment, and architectural documentation.
- Architecture docs · UML diagrams and runbooks that define the intended controller behavior.
docs/diagrams/class_diagram.puml - Ops scripts · Seed, monitoring, webhook, and packaging scripts used in demos and deployment.
scripts/start-scemas.sh
Connections 24
- 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.