System architecture

Terminal retirement — local implementation, 2026-10-20

The current working tree removes interactive terminals and Redis while preserving command/script Remote Actions and authorized session/transcript history with existing retention. Admin has a read-only history viewer; Core advertises no terminal capability and legacy terminal operations cannot create work. This implementation is local and awaits user testing; older published implementation descriptions below remain historical. See the retirement plan and evidence.¹

Shape

MonStaff is a modular monolith with separate desktop, admin and documentation clients. The backend owns authentication, authorization, persistence and external integration orchestration.

Desktop Rust Core + Tauri GUI/CLI ─┐
Admin React/Vite ────────┼── HTTPS/JWT ──> Backend Fastify
CI release/update ───────┘                    │
                                             ├── PostgreSQL / Prisma
                                             ├── S3 / MinIO
                                             ├── optional Collector / ClickHouse agent telemetry
                                             ├── optional OnlyOffice report authoring
                                             ├── optional GitHub OAuth, REST, GraphQL
                                             └── optional Hubstaff OAuth/API

MonStaff Core ──> OS collectors, PTY/ConPTY, agent sidecar and signed local-AI sidecar

Website Astro/Starlight ──> static documentation projected from this wiki
Shared TypeScript/Zod ────> API and model contracts; Rust protocol crate ──> Core/client contract

Primary flows

1. A human authenticates with native password/TOTP or optional GitHub PKCE and receives the same MonStaff session contract.
2. A user selects a native project and optional provider-neutral work item, then starts a time entry.
3. Activity and application context are accumulated locally; screenshots upload through presigned S3 URLs.
4. The admin queries organization analytics and configures tracking policies.
5. Optional GitHub synchronization projects external repositories, work items, iterations and transitions through explicit link rows; Hubstaff uses durable segmented import jobs.
6. A signed desktop installation shares identity across read-only compliance, managed Local AI packs and separately authorized command/script Remote Actions capability.
7. Agent clients normalize lifecycle/chat records through a loopback bridge and OTLP collector; ClickHouse stores telemetry while PostgreSQL stores finalized developer allocation and timesheet projections.
8. Customer reporting starts from explicit customer-project visibility and time allocation. Definitions, template versions, snapshots, runs, artifacts and recipient snapshots are immutable; leased renderer, delivery, schedule and retention workers checkpoint external boundaries.²

Trust boundaries

• Desktop to backend: identity token and sensitive behavioral data.
• Admin to backend: organization-wide reporting and settings authority.
• Backend to GitHub/Hubstaff: encrypted third-party OAuth credentials.
• Backend to desktop: signed device requests, bounded posture evidence, encrypted remote output and model-pack authorization.
• Desktop to local AI sidecar: minimized context over a fixed local process contract; no external AI/Ollama runtime is part of the release candidate.
• Backend to S3: screenshot and desktop-update objects.
• CI to cloud: release token, registry and cluster deployment authority.

Architectural direction

The release candidate retains the modular monolith with centralized grant-aware authorization, durable OAuth/session/job state and workers for imports, synchronization, retention and delivery snapshots. Dangerous device capabilities remain separately enabled and audited. See the decision register and plan registry.

Footnotes

1. Local interactive-terminal and Redis retirement. ↩

2. Active AT, TS, CU and RP workstreams at maximum repository-local implementation. ↩