The Hub (/hub/*)

The Hub — agentic control dashboard

The Hub is the private administration interface of Synedre OS. Accessible only from the mothership VPS via a secure tunnel, it enables full control over the agentic harness: agents, projects, runs, negotiations, memory, and infrastructure.

A dedicated cockpit application

The Hub is built on a standalone Nuxt application, distinct from any other application surface. It inherits no localization module and no theme management: it is French-only and enforces permanent dark mode (the light/dark toggle was removed in May 2026). This choice of visual austerity reflects the operational nature of the tool.

Layered functional architecture

The Hub is not a monolith. Its features are distributed across independent modules, loaded as Nuxt layers at startup. Each layer brings its own pages, its own API endpoints, and its own server-side code, automatically discovered by the routing engine.

Two categories are distinguished:

• Core components — pages and endpoints directly carried by the main application: general dashboard, cost view, backup management, maintenance dial.
• Thematic modules — each encapsulates a business or technical domain and exposes its own /hub/* routes along with its own API endpoints.

In total, the Hub aggregates 27 active functional layers, covering domains as varied as agent management, project tracking, billing, memory, automations, SEO monitoring, and internal training.

Architecture note: these layers are declared via the extends: key in the Nuxt configuration, and not via the modules: key. Confusing the two causes load errors at startup. Each layer has its own minimal Nuxt configuration file.

Page and module map

Core pages

The main application directly exposes several global control pages:

• Root /hub — automatic redirect (302) to the main dashboard; this is not a standalone page.
• SRE view — mothership reliability supervision.
• Cost view — expense tracking, accessible from the main navigation; a detailed sub-view breaks down costs by project and by annual budget.
• Agentic learning view — skill progression tracking dashboard.
• Backup view — infrastructure backup status.
• Maintenance dial — supervision interface for the documentary and technical health of the system, detailed below.

Maintenance dial — two tabs

The maintenance dial is the internal observatory for system health. It consists of two tabs:

1. Health dashboard — a global gauge aggregates four system health dimensions: proprioception, technical debt, learning, and automations. A 7-day trend chart accompanies a documentary drift table, classifying discrepancies by type: dead reference, outdated published document, code more recent than its documentation, unpublished document.
2. External review — the operator selects a chapter of public documentation, generates a prompt stripped of any sensitive data, submits it to an external AI model, then pastes the response into the form for archiving. The submission history is browsable. The maximum size of a submitted response is 50,000 characters. Eleven chapters are eligible for this external review.

Pages carried by thematic modules

The 27 modules collectively contribute 49 additional pages under /hub/*. The table below shows their distribution by functional domain:

Functional domain	Pages /hub/*
Agents & agentic operations	38 pages: main dashboard, agent profiles, brainstorm, projects (list, profile, kanban, work), clients, advisory, constitution, dispatch, doctrine, emails, hooks, inbox, legal, memory (navigation, RAG search), negotiations, questions, reactor, runs (list, profile, atlas), sessions, settings, skills, pending skills, user model
Backlog & planning	3 pages: backlog, planning, system backlog
Cockpits & projects	2 pages: project profile, cockpits view
Exercises & training	2 pages: exercise list, detail by agent
Scars	1 page: scar registry
Conducts	1 page: conduct table
Automations	1 page: system automation management
SEO monitoring	1 page: technical multi-tenant SEO cockpit (404 rate, click/impression trend, observation or auto-remediation mode, alert log) — accessible by direct URL, absent from the side navigation

Public surface of the Exercises module: this module also exposes four public pages on synedre.com (outside the /hub space): exercise list, history, scars, and trial detail. These pages are not counted among the 49 hub pages above.

Modules with no Vue page (server-only)

Several modules expose no interface page. They exclusively provide API endpoints and a persistence layer, consumed by other Hub pages or by Python automations. They cover in particular: internal academic management, autoblog article tracking, client configuration, daily messaging, billing, incidents, meetings, utility tools, and other cross-cutting services.

A module dedicated to Hub statistics exposes summary data (/api/stats), constitution and charter resources (/api/un composant interne, /api/un composant interne), and avatar statistics — without ever presenting its own interface page.

Note: the expertise pages module contributes public SEO pages (outside /hub/), not cockpit pages.

Side navigation — the seven zones

The cockpit navigation bar is organized into seven thematic zones, restructured in May 2026 to reflect the operational workflow:

Zone	Entries
Control	Main dashboard · Emails · Brainstorm · User model
Business	Clients · Negotiations · Advisory · Legal
Execution	Backlog · Project · Runs · Questions · New task · Sessions
Doctrine & Learning	Doctrine · Constitution · Scars · Exercises
Agentic	Agents · Reactor · Skills · Pending skills · System automations · Dispatch · Hooks & Reflexes · Agentic learning
Memory	Brain (memory navigation) · Recall RAG (semantic search)
System	SRE · Maintenance dial · Costs · Backups · Settings

A separate link, placed at the bottom of the navigation, provides access to the PaaS e-commerce surface. This surface is served by an application distinct from the Synedre OS cockpit — it is not an internal Hub page.

Active behavior: a navigation entry is marked as active on exact match of the current route or on prefix match (sub-route). The /hub root always redirects to the main dashboard and does not constitute a destination in its own right.

The three endpoint families

The API route split is not merely organizational: it carries an access-rights semantics. Three prefixes coexist, each with its own protection level.

• /api/bo/* — founder/cron back-office surface, protected upstream by the infrastructure gate, sometimes without an additional application-layer guard.
• /api/hub/* — employee cockpit surface, with near-systematic session verification.
• /api/voice/* — audio transcription, with session verification and CSRF defense.

Back-office surface

This family groups the endpoints reserved for founder operations and scheduled tasks. It is divided into several functional sub-domains:

• Learning: browsing the learning feed, applying and updating entries.
• Project: triggering and editing project explosions, checking status, launching a phase.
• Quality indicators: reading scar KPIs.
• Costs: dashboard, budget (read/write), time series, per-project view.
• Inbox: synchronization, list, detail, attachments, linking to a project.
• Mothership infrastructure: backup list, download, reading documentation health status and detected drift.
• External documentation review: list of eligible chapters, generation of the sanitized prompt for an external AI model, review history (with filters), submission of an external review.
• SRE metrics: reading reliability metrics.
• Tenants: automatic dispatch status per tenant.

Authentication specifics: certain endpoints in this surface rely exclusively on the infrastructure gate (knock cookie + slug) rather than on application-layer session verification. This is notably the case for the inbox synchronization endpoint, triggered by a system cron job.

This choice is tied to a technical constraint: IMAP synchronization blocks the Node.js event loop and is therefore excluded from the internal scheduler. The seven other periodic tasks are managed by that scheduler:

• E-mail queue processing (every 2 minutes)
• Availability monitoring (every 15 minutes)
• Dictionary watch (every 30 minutes)
• Dependency monitoring (daily, 2 a.m.)
• Daily audit meeting (daily, 8 a.m.)
• SSL certificate monitoring (daily, 9 a.m.)
• Brand watch (daily, 12 p.m.)

Employee cockpit surface

This family is by far the largest. It groups the endpoints used by the cockpit interfaces: management of agents, projects, runs, negotiations, advisory, clients, brainstorming, memory, doctrine, skills, sessions, questions, tasks, the user model, settings, agent allocation, and the atlas.

Employee session verification is applied in the vast majority of files in this surface. Exceptions are internal helpers or SSE (Server-Sent Events) streams. The standard pattern is written as:

export default defineEventHandler(async (event) => {
  requireEmployeeSession(event)
  // …
})

A subset of endpoints specifically manages the lifecycle of a project: active runs, discovered bugs, CLI sessions (start, stop, reset), real-time agent event streams (SSE), as well as actions on a given run (response draft, fix trigger, profile, event stream).

Audio transcription surface

A single endpoint accepts a WAV audio file as multipart and returns the transcribed text, the detected locale, the duration in milliseconds, the model used, and the backend invoked. The default locale is French.

The applied safeguards are as follows:

• Mandatory employee session verification.
• Maximum file size: 5 MB.
• Rate limit: 100 transcriptions per 5-minute window per session.
• Audio is never persisted to disk: in-memory processing only.
• CSRF defense via Origin/Referer matching against the Host header.

Authentication

The two-layer model

Security relies on an architecture with two independent levels:

• Infrastructure layer: encrypted tunnel to the server's local port, combined with an nginx knock gate (cookie + slug). Any request that clears this gate is already qualified as "owner".
• Application layer: a startup middleware automatically injects a signed "founder" session cookie for any request that does not present one. As a result, application-layer session verification always passes on the mothership runtime — real security is entirely carried by the infrastructure.

This auto-session middleware is strictly limited to the mothership. It does not exist in the product core or in tenant instances. On public tenants, session verification remains mandatory and constitutes the true application-layer guard.

The session verification functions

Four utility functions govern application-layer access control:

• Session read: decodes the session cookie (HMAC-SHA256 signed JSON). Returns null if the cookie is absent or invalid.
• Employee guard (requireEmployeeSession): returns the session if the user type is employee, raises a 401 error otherwise. This is the standard guard for the cockpit and transcription surfaces.
• Founder guard: additionally requires SaaS Super-Admin status, 403 error otherwise.
• Role guard: requires a given business role or SaaS Super-Admin status.

The SaaS Super-Admin list is a static whitelist in the source code — intentionally not stored in the database, so that any modification requires a code change and an explicit review.

The session carries the following fields: employee identifier, e-mail, first name, last name, role, profile identifier, client identifier, user type, administrator flag.

The routing middleware is disabled

The Nuxt routing middleware on the cockpit side is intentionally reduced to a no-op (it returns immediately without performing any check). The nginx gate and the encrypted tunnel provide upstream protection; an additional check on the Nuxt side would be redundant.

This middleware remains declared because many pages reference it in their route metadata. The no-op being intentional, this declaration has no functional impact.

Cockpit layout

The cockpit relies on a single layout that structures all pages of the interface. This layout inherits from no parent layout: the mothership is a standalone application.

Notable points:

• The identity displayed in the interface is a static stub — dynamic Nuxt authentication has been removed; the infrastructure layer guarantees the operator's actual identity.
• Page titles follow the template … — Synedre OS.
• Real-time pages (reactor, project cockpit) are rendered client-side only (ssr: false), allowing them to maintain persistent SSE connections.

Consistency note: the layout header comment lists navigation entries incompletely. The actual navigation structure, defined in the layout's sections array, always takes precedence over these comments.

Hub Console Surfaces

The Hub exposes several agent control consoles. Each console is a specialized view over a specific type of activity: active runs, development projects, commercial negotiations, fleet supervision, or live orbital view. Data is centralized in a shared model, exposed via Python business entities and relational tables.

Scoped Executions (Runs)

A run represents a scoped Atlas execution — whether triggered by email, hub console chat, or a cron job. Each run carries the following attributes: unique identifier, trigger source, trigger type, scope (mothership or tenant), title, status, reference type and identifier, creation and completion dates.

• Source atlas-inbox: run triggered by an incoming email.
• Source console: run triggered by the Hub chat.
• Emails classified as questions, noise, or project intent do not generate a run: they remain in their dedicated spaces (questions, projects).
• An automaton task run (task run) is a distinct entity — not to be confused with an Atlas run.

The runs view lists all executions, filterable by scope. A per-agent detail view allows browsing the event stream in real time via an SSE feed, reading or posting a draft reply, and triggering a corrective action.

Projects, Work Units, and Tasks

A project is the control unit for a development effort. It breaks down into work units, which in turn break down into tasks. This three-level hierarchy structures all operational tracking.

Hierarchical Model

• Project: development effort, carried by a dedicated entity. Linked to N work units.
• Work unit: delivery unit within a project. Linked to N tasks.
• Task: atomic action. May depend on other tasks (directed acyclic graph).
• Junction tables associate agents with projects on one hand, and agents with work units on the other.

The canonical creation of a project follows a seven-step procedure that initializes the full skeleton (project + initial work units + tasks).

Architecture note: the data model carries a historical naming debt. Project and work unit entities use a prefix inherited from the PaaS era, while tasks and junction tables have already migrated to the target prefix. No intermediate view or table bearing the new prefix exists yet for projects and work units themselves — migration is ongoing following the Strangler Fig pattern.

Concurrency Control and Audit Entities

Component	Role	Key points
Project lock	Prevents two sessions from concurrently modifying the same project	Composite key (project × owner type); possible owners: user session or spawned agent subprocess. 30-minute TTL with heartbeat. Backward-compatibility mode when the table is absent.
Lock error	Exception raised when the lock is held by another active session	Intercepted by the project competency layer before any modification.
Explosion audit log	Traces each invocation of the automatic work-unit discovery pipeline	One row per invocation; lifecycle pending → success | validation_failed | llm_failed | killswitched. Stores the AI model used, provider, tokens consumed, estimated cost, produced JSON plan, and number of work units created. 90-day retention. A 24-hour quota triggers a configurable kill-switch.
Task dependencies (DAG)	Models blocking relationships between tasks within a work unit	Validations on insertion: no self-dependency, tasks must belong to the same work unit, no cycle (DFS detection). Raises typed exceptions for detected cycles or cross-work-unit dependency attempts.

Project Console Views and Features

• Active project list view and per-work-unit kanban view.
• Cockpit view: active agent sessions on a project.
• Live CLI console: session start, stop, reset, and real-time agent event stream (SSE).
• Available actions: draft mission statement, launch in automatic mode, archive, close with email draft, switch to brainstorming mode, manage deliverables, manage team, audit relevance.

Synedre CLI Console

The cockpit embeds a control surface for a real Claude CLI session, accessible from the browser. The mechanism relies on a daemon running on the host machine (not inside an isolated container) that relays interactions.

• Status: queries the daemon and returns a state { ok, alive, info }. If the daemon does not respond, the surface returns alive: false without exposing the internal error message to the client — an explicit security behavior.
• Keystroke forwarding: transmits keyboard input to the active session.
• Real-time stream: SSE stream of the session output.

Note: the host daemon architecture (rather than container) is intentional — it resolves an isolation issue identified during a dedicated work unit on this topic.

Negotiations

Negotiations model the inbound lead processing pipeline. An incoming email is analyzed by Atlas; if the detected intent is negociation, a negotiation item is created and appears in the dedicated console.

• Negotiation list view and per-negotiation detail view.
• Available actions on a negotiation: assign, manage contacts, manage deliverables (including attached files), view related emails, create an event, track the timeline, manage commercial proposals.
• Per proposal: decision endpoint (accept / reject).
• Work start action: transitions the negotiation into an operational project.

Fleet Module

The fleet module is a server-only component with no dedicated Hub interface at this time. It exposes a data schema intended to be consumed by a future dedicated interface.

The fleet registry data model includes, for each client instance: identifier, name, domain, subscribed plan, MRR, setup fee, status, VPS region, administration URL, configured AI provider, and configured AI model.

Warning: this registry contains legacy columns intended to store secrets (administration passwords, API keys). This schema is inherited from the PaaS era and is inconsistent with the zero-secret-in-business-database doctrine. It is pending audit and must not be considered the canonical source of operational secrets.

The operational source of truth for client VPS management remains the main VPS registry. The exact relationship between that registry and the fleet model is to be confirmed. Operational tenant management is performed primarily through the site and client administration consoles.

Orbital View — Reactor

The Reactor view is a live orbital representation of agent activity. It is organized into three concentric rings according to each agent's role:

• Ring 1 (center): director agents.
• Ring 2: scoping and execution agents.
• Ring 3 (periphery): validation agents.

An octopus logo occupies the center. The view is fed in real time via SSE. It is rendered client-side only (no server-side rendering). It is adapted from the public marketing page of the reactor.

Entry Points for Extending the Hub

Objective	Mechanism
Add an entry to the sidebar	Modify the navigation sections array in the main Hub layout.
Add a /hub/X page	Create the page in the relevant module and declare the hub layout in the page metadata.
Add a cockpit endpoint	Create the endpoint in the relevant module's API folder and apply the employee session verification middleware to it.
Understand authentication	Consult the session utilities and the auto-session middleware, which handle HMAC signing of Hub session cookies.
Plug in a new module	Declare the module in the Nuxt extension configuration and provide a manifest and local configuration for the module.
Work on runs and projects (database)	Use the Python business entities from the repository and the corresponding tables: Atlas runs, projects, work units, tasks, negotiations — all in the mothership schema.
Consult the maintenance and documentation drift dashboard	Use the Hub maintenance view and its associated endpoint, which rely on the documentation health and detected drift tables.
External documentation review	Use the external review panel component and its dedicated endpoints, backed by the external reviews table.
Reflex and hook registry	Consult the Hub hooks view and its listing endpoint, which exposes the reflex registry organized by level (trunk / arms).
Project lock (CLI concurrency)	Use the distributed locking entity: operations try_acquire, force_claim, release, heartbeat.
Automatic discovery invocation audit	Consult the audit entity: methods for retrieving recent invocations and counting over a 24-hour window.
Task dependencies (DAG)	Use the dependency entity: operations add_dep, remove_dep, list_deps_for_travail with DFS cycle detection.

Secret management: no secret is stored in plaintext in the codebase. The Hub session cookie signing key is consumed via HMAC by the session cryptographic layer; its environment variable resides in environment files excluded from the repository, in accordance with the secrets doctrine.