# carlosazaustre/tenacitos architecture

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

- Interactive diagram: https://gitdiagram.com/carlosazaustre/tenacitos
- Repository: https://github.com/carlosazaustre/tenacitos

## Overview

1. **Overall shape**  
   TenacitOS is a single Next.js 15 application that acts as a mission-control dashboard for an existing OpenClaw installation. There is no separate backend service: the app’s server routes read local files, OpenClaw workspace data, system state, and a local SQLite store directly on the host.

2. **Primary trust boundary and auth**  
   `src/middleware.ts` is the main gatekeeper. Almost everything is protected; the notable public entry points are login and health. Authentication is cookie-based, with a password login flow in `/api/auth/login` and logout in `/api/auth/logout`. The README also calls out rate limiting on failed login attempts and secure cookie settings in production.

3. **Core external dependency: OpenClaw workspace**  
   The central data source is the OpenClaw directory (`OPENCLAW_DIR`, defaulting to `/root/.openclaw`). TenacitOS discovers agents from `openclaw.json` and reads per-agent workspace content, sessions, memory, logs, and related metadata from the host filesystem. This means the dashboard is a read/write control surface over an existing local agent runtime, not an isolated app database.

4. **Local app state files**  
   The `data/` directory holds JSON-backed app state such as cron jobs, activities, notifications, configured skills, and tasks. These files are the persistence layer for dashboard-managed content that is not sourced directly from OpenClaw. The `.example.json` files show that the repo expects these files to be created on deployment and kept out of version control.

5. **Cost tracking pipeline**  
   Cost analytics are handled separately from the main OpenClaw data flow. Usage is collected by `scripts/collect-usage.ts` from OpenClaw’s SQLite databases and aggregated into local cost data used by the `/costs` and `/analytics` views and their API routes. This is an offline ingestion step, with `scripts/setup-cron.sh` intended to automate hourly collection.

6. **API layer as the backend façade**  
   The `src/app/api/*` route handlers are the main server-side API surface. They expose subsystem-specific endpoints for agents, activities, analytics, auth, browse, costs, cron, files, git, logs, memory search, notifications, office, reports, search, sessions, skills, system, terminal, weather, and health. Several routes are specialized for streaming or stats (`activities/stream`, `logs/stream`, `system/stats`, `system/monitor`), indicating a mix of polling and event-style updates.

7. **Dashboard UI structure**  
   The protected dashboard lives under `src/app/(dashboard)`. Each top-level page corresponds to a subsystem panel: agents, activity, analytics, calendar, costs, cron, files, git, logs, memory, reports, search, sessions, settings, skills, system, terminal, and workflows. Shared chrome and presentation live in `src/components/TenacitOS`, which provides the OS-like shell elements such as top bar, dock, status bar, and section/metric rows.

8. **Main functional subsystems**  
   The app is organized around a few major domains: agent management and status, activity and session observability, memory and file browsing/editing, cron scheduling and run history, system monitoring, and search. These domains are surfaced both as dashboard pages and as matching API endpoints, which keeps the architecture consistent: page → API route → local/OpenClaw data source.

9. **Streaming and real-time views**  
   Activity and log feeds have dedicated stream endpoints, and system monitoring has live stats/monitor routes. On the client side, this is reflected in charts, heatmaps, dashboards, and status widgets that likely refresh periodically or subscribe to streamed updates. The architecture favors near-real-time observability without introducing a message broker.

10. **3D office as a separate presentation surface**  
   The `/office` route is an alternate, unprotected visualizer built with React Three Fiber. It uses `src/components/Office3D` plus `public/models/` for per-agent GLB avatars, with fallback procedural or voxel avatars when models are absent. This surface is mostly presentational, but it still reflects the same underlying agent inventory and branding config.

11. **File, terminal, and workspace control boundaries**  
   File operations are exposed through dedicated API routes for list, preview, upload, write, mkdir, delete, and download. The terminal feature is explicitly read-only and guarded by a command allowlist to avoid arbitrary execution. That makes the file and terminal subsystems the two most sensitive control planes in the app.

12. **Supporting libraries and runtime assumptions**  
   Shared logic in `src/lib` handles path resolution, pricing, cron parsing, skill parsing, activity logging, usage collection, and database/query access. `src/config/branding.ts` centralizes env-driven branding. The stack is Node.js 22, Next.js App Router, React 19, Tailwind CSS v4, Recharts for charts, Lucide for icons, and SQLite via `better-sqlite3` for usage/cost analytics.

13. **Operational scripts and deployment model**  
   The repo includes helper scripts for usage collection, pre-commit checks, and cron setup, which indicates the app is intended to be operated alongside the OpenClaw host rather than deployed as a generic SaaS. The production model is a single long-lived Node process behind PM2/systemd and optionally a reverse proxy like Caddy.

Main entry points: [`data/cron-jobs.example.json`](https://github.com/carlosazaustre/tenacitos/blob/main/data/cron-jobs.example.json) (App state), [`src/middleware.ts`](https://github.com/carlosazaustre/tenacitos/blob/main/src/middleware.ts) (Middleware), [`src/app/api/agents/route.ts`](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/agents/route.ts) (API façade), [`scripts/collect-usage.ts`](https://github.com/carlosazaustre/tenacitos/blob/main/scripts/collect-usage.ts) (Usage pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App surface"]
  node_node_middleware["Middleware<br/>auth gatekeeper<br/>[middleware.ts]"]
  node_node_login["Login<br/>public auth UI<br/>[page.tsx]"]
  node_node_dashboard_shell["Dashboard shell<br/>protected app<br/>[layout.tsx]"]
  node_node_dashboard_panels["Subsystem panels<br/>dashboard pages<br/>[page.tsx]"]
  node_node_office["Office view<br/>3D presentation<br/>[page.tsx]"]
end

subgraph group_grp_api["API façade"]
  node_node_api_auth["Auth API<br/>session endpoints<br/>[route.ts]"]
  node_node_api_facade["API façade<br/>route surface<br/>[route.ts]"]
  node_node_api_streams["Live feeds<br/>stream/stats routes<br/>[route.ts]"]
  node_node_api_files["File control<br/>workspace files API<br/>[route.ts]"]
  node_node_api_system["System API<br/>host observability<br/>[route.ts]"]
  node_node_api_terminal["Terminal API<br/>restricted shell<br/>[route.ts]"]
  node_node_api_office["Office API<br/>presentation data<br/>[route.ts]"]
end

subgraph group_grp_ui["UI system"]
  node_node_components_shell["TenacitOS UI<br/>app chrome<br/>[index.ts]"]
  node_node_components_domain["Feature components<br/>dashboard widgets<br/>[ActivityFeed.tsx]"]
  node_node_components_office3d["Office3D<br/>3D scene components<br/>[Office3D.tsx]"]
end

subgraph group_grp_core["Core logic"]
  node_node_lib_core["Core libs<br/>shared logic<br/>[paths.ts]"]
  node_node_branding["Branding<br/>env config<br/>[branding.ts]"]
end

subgraph group_grp_data["Data and ops"]
  node_node_data_state[("App state<br/>json persistence")]
  node_node_openclaw[("OpenClaw workspace<br/>host filesystem")]
  node_node_usage_pipeline["Usage pipeline<br/>sqlite ingestion<br/>[collect-usage.ts]"]
  node_node_scripts_ops["Ops scripts<br/>deployment helpers<br/>[setup-cron.sh]"]
end

node_node_middleware -->|"allows"| node_node_login
node_node_middleware -->|"protects"| node_node_dashboard_shell
node_node_middleware -->|"protects"| node_node_api_facade
node_node_login -->|"uses"| node_node_api_auth
node_node_dashboard_shell -->|"renders with"| node_node_components_shell
node_node_dashboard_panels -->|"renders with"| node_node_components_domain
node_node_office -->|"renders with"| node_node_components_office3d
node_node_api_facade -->|"reads"| node_node_openclaw
node_node_api_facade -->|"reads/writes"| node_node_data_state
node_node_api_files -->|"accesses"| node_node_openclaw
node_node_api_system -->|"observes"| node_node_openclaw
node_node_api_terminal -->|"controls"| node_node_openclaw
node_node_api_office -->|"reflects"| node_node_openclaw
node_node_lib_core -->|"interprets"| node_node_openclaw
node_node_lib_core -->|"persists"| node_node_data_state
node_node_usage_pipeline -->|"collects from"| node_node_openclaw
node_node_usage_pipeline -->|"aggregates into"| node_node_data_state
node_node_scripts_ops -->|"automates"| node_node_usage_pipeline
node_node_scripts_ops -->|"prepares"| node_node_data_state
node_node_branding -->|"styles"| node_node_components_shell
node_node_branding -->|"brands"| node_node_office
node_node_api_streams -->|"feeds"| node_node_dashboard_panels

click node_node_middleware "https://github.com/carlosazaustre/tenacitos/blob/main/src/middleware.ts"
click node_node_login "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/login/page.tsx"
click node_node_dashboard_shell "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/(dashboard)/layout.tsx"
click node_node_dashboard_panels "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/(dashboard)/page.tsx"
click node_node_office "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/office/page.tsx"
click node_node_api_auth "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/auth/login/route.ts"
click node_node_api_facade "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/agents/route.ts"
click node_node_api_streams "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/activities/stream/route.ts"
click node_node_api_files "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/files/route.ts"
click node_node_api_system "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/system/route.ts"
click node_node_api_terminal "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/terminal/route.ts"
click node_node_api_office "https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/office/route.ts"
click node_node_components_shell "https://github.com/carlosazaustre/tenacitos/blob/main/src/components/TenacitOS/index.ts"
click node_node_components_domain "https://github.com/carlosazaustre/tenacitos/blob/main/src/components/ActivityFeed.tsx"
click node_node_components_office3d "https://github.com/carlosazaustre/tenacitos/blob/main/src/components/Office3D/Office3D.tsx"
click node_node_lib_core "https://github.com/carlosazaustre/tenacitos/blob/main/src/lib/paths.ts"
click node_node_branding "https://github.com/carlosazaustre/tenacitos/blob/main/src/config/branding.ts"
click node_node_data_state "https://github.com/carlosazaustre/tenacitos/blob/main/data/cron-jobs.example.json"
click node_node_usage_pipeline "https://github.com/carlosazaustre/tenacitos/blob/main/scripts/collect-usage.ts"
click node_node_scripts_ops "https://github.com/carlosazaustre/tenacitos/blob/main/scripts/setup-cron.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_node_middleware,node_node_login,node_node_dashboard_shell,node_node_dashboard_panels,node_node_office toneBlue
class node_node_api_auth,node_node_api_facade,node_node_api_streams,node_node_api_files,node_node_api_system,node_node_api_terminal,node_node_api_office toneAmber
class node_node_components_shell,node_node_components_domain,node_node_components_office3d toneMint
class node_node_lib_core,node_node_branding toneRose
class node_node_data_state,node_node_openclaw,node_node_usage_pipeline,node_node_scripts_ops toneIndigo
```

## Components

### App surface

Protected dashboard, login, office, and route entrypoints

- [Middleware](https://github.com/carlosazaustre/tenacitos/blob/main/src/middleware.ts): auth gatekeeper · Main request gate that protects dashboard routes and leaves login/health public · `src/middleware.ts`
- [Login](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/login/page.tsx): public auth UI · Cookie-based sign-in entry point and logout flow · `src/app/login/page.tsx`
- [Dashboard shell](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/(dashboard)/layout.tsx): protected app · Next.js dashboard layout and home entry for the main mission-control surface · `src/app/(dashboard)/layout.tsx`
- [Subsystem panels](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/(dashboard)/page.tsx): dashboard pages · Pages for agents, activity, analytics, costs, cron, files, logs, memory, search, sessions, settings, skills, system, terminal, workflows, and more · `src/app/(dashboard)/page.tsx`
- [Office view](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/office/page.tsx): 3D presentation · Alternate office-style visualization built with React Three Fiber · `src/app/office/page.tsx`

### API façade

Route handlers that expose host and workspace data

- [Auth API](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/auth/login/route.ts): session endpoints · Login and logout handlers that establish and clear the dashboard session · `src/app/api/auth/login/route.ts`
- [API façade](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/agents/route.ts): route surface · Main subsystem endpoints for agents, activities, analytics, browse, costs, cron, files, git, logs, memory, notifications, reports, search, sessions, skills, system, terminal, weather, and health · `src/app/api/agents/route.ts`
- [Live feeds](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/activities/stream/route.ts): stream/stats routes · Streaming and monitoring routes for activity, logs, and system live status · `src/app/api/activities/stream/route.ts`
- [File control](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/files/route.ts): workspace files API · List, preview, write, upload, mkdir, delete, download, and workspace file access routes · `src/app/api/files/route.ts`
- [System API](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/system/route.ts): host observability · System status, services, stats, and monitor endpoints for host health and runtime visibility · `src/app/api/system/route.ts`
- [Terminal API](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/terminal/route.ts): restricted shell · Read-only terminal surface guarded by an allowlist · `src/app/api/terminal/route.ts`
- [Office API](https://github.com/carlosazaustre/tenacitos/blob/main/src/app/api/office/route.ts): presentation data · Data endpoint backing the office visualization and agent avatars · `src/app/api/office/route.ts`

### UI system

Shared components and presentation shells

- [TenacitOS UI](https://github.com/carlosazaustre/tenacitos/blob/main/src/components/TenacitOS/index.ts): app chrome · OS-like shell components such as top bar, dock, status bar, rows, and metrics · `src/components/TenacitOS/index.ts`
- [Feature components](https://github.com/carlosazaustre/tenacitos/blob/main/src/components/ActivityFeed.tsx): dashboard widgets · Domain widgets for activity feeds, agents, files, search, cron, skills, system info, notifications, markdown, calendar, and charts · `src/components/ActivityFeed.tsx`
- [Office3D](https://github.com/carlosazaustre/tenacitos/blob/main/src/components/Office3D/Office3D.tsx): 3D scene components · 3D office scene, avatars, furniture, controls, and model fallbacks · `src/components/Office3D/Office3D.tsx`

### Core logic

Shared server-side helpers and runtime glue

- [Core libs](https://github.com/carlosazaustre/tenacitos/blob/main/src/lib/paths.ts): shared logic · Path resolution, cron parsing, pricing, skill parsing, activity logging, and database/query helpers · `src/lib/paths.ts`
- [Branding](https://github.com/carlosazaustre/tenacitos/blob/main/src/config/branding.ts): env config · Environment-driven branding and identity configuration · `src/config/branding.ts`

### Data and ops

Local persistence, workspace sources, and operational scripts

- [App state](https://github.com/carlosazaustre/tenacitos/blob/main/data/cron-jobs.example.json): json persistence · Local JSON-backed state for cron jobs, activities, notifications, skills, and tasks · `data/cron-jobs.example.json`
- **OpenClaw workspace**: host filesystem · External OpenClaw directory and agent runtime data discovered from host files and workspace metadata
- [Usage pipeline](https://github.com/carlosazaustre/tenacitos/blob/main/scripts/collect-usage.ts): sqlite ingestion · Offline collection and aggregation of OpenClaw usage into local cost data for analytics · `scripts/collect-usage.ts`
- [Ops scripts](https://github.com/carlosazaustre/tenacitos/blob/main/scripts/setup-cron.sh): deployment helpers · Cron setup, usage collection wrapper, and pre-commit checks for host operation · `scripts/setup-cron.sh`

## Connections

- Middleware → Login: allows · Public entry path for authentication
- Middleware → Dashboard shell: protects · Gates dashboard routes behind the session cookie
- Middleware → API façade: protects · Secures the server API surface
- Login → Auth API: uses · Submits credentials and clears sessions
- Dashboard shell → TenacitOS UI: renders with · Uses shared shell chrome and status elements
- Subsystem panels → Feature components: renders with · Uses shared widgets and charts across panels
- Office view → Office3D: renders with · Uses the dedicated 3D office scene components
- API façade → OpenClaw workspace: reads · Most routes project host workspace data into the UI
- API façade → App state: reads/writes · Subsystem routes persist dashboard-managed app state
- File control → OpenClaw workspace: accesses · File browser and editor operate on workspace files
- System API → OpenClaw workspace: observes · System views draw host and runtime status from the workspace host
- Terminal API → OpenClaw workspace: controls · Restricted command execution against the host runtime
- Office API → OpenClaw workspace: reflects · Office avatars and inventory mirror the same agent set
- Core libs → OpenClaw workspace: interprets · Resolves workspace paths, parses skills and cron data, and queries usage sources
- Core libs → App state: persists · Helpers load and store dashboard-owned JSON state
- Usage pipeline → OpenClaw workspace: collects from · Reads SQLite usage data from the host installation
- Usage pipeline → App state: aggregates into · Produces local cost data consumed by analytics views
- Ops scripts → Usage pipeline: automates · Wraps hourly or scheduled usage collection
- Ops scripts → App state: prepares · Bootstraps and maintains expected local state files
- Branding → TenacitOS UI: styles · Centralized branding influences shell presentation
- Branding → Office view: brands · Office view uses the same identity configuration
- Live feeds → Subsystem panels: feeds · Supplies near-real-time activity, log, and system updates
