# bluenot3/fus3 architecture

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

- Interactive diagram: https://gitdiagram.com/bluenot3/fus3
- Repository: https://github.com/bluenot3/fus3

## Overview

1. **Overall shape**
   - This repo is a **Next.js App Router control plane** for operational management, not a single-purpose app. The UI, API layer, persistence, and integration clients are all in one repository, with Supabase and external service runners providing the stateful/back-end pieces.

2. **Primary user-facing surfaces**
   - `app/page.tsx` is the main command-center entry point.
   - `app/ingest/page.tsx` is a separate knowledge-ingestion workspace.
   - `app/wix/page.tsx` is a dedicated Wix operations surface.
   - The UI is composed from shell-style components in `components/`, especially `command-center-shell.tsx`, `knowledge-ingest-shell.tsx`, `wix-command-center.tsx`, and `operational-widgets.tsx`.

3. **Interaction model**
   - The app is designed around a **dashboard + command palette** workflow rather than navigation-heavy CRUD screens.
   - `components/command-palette.tsx` and the shell components suggest keyboard-driven actions and widget-based operations as the main interaction pattern.
   - `components/mobile-command-center.tsx` indicates the same operational experience is adapted for mobile.

4. **API layer as the integration boundary**
   - All backend capabilities are exposed through `app/api/*` route handlers.
   - The key route groups are:
     - `connectors` for provider discovery/registration
     - `metrics` for operational telemetry
     - `secrets` for credential CRUD
     - `ingest` for content/knowledge intake
     - `telegram/*` for bot management and test messaging
     - `ollama/models` for local/remote model discovery
     - `wix/overview` for Wix-specific status/summary
     - `exports/[jobId]` for export job status or retrieval
   - This API layer is the main boundary between the browser UI and all backend systems.

5. **Persistence and server-side state**
   - `lib/supabase/server.ts` and `supabase/schema.sql` show Supabase is the main durable store.
   - The README confirms Supabase is used for **metrics and secrets persistence**.
   - Architecturally, Supabase sits behind the API routes and is the system of record for operational data that must survive process restarts.

6. **Secrets handling**
   - `lib/secrets/crypto.ts` and `lib/secrets/manager.ts` define a dedicated secret-management subsystem.
   - Secrets are not stored raw; they are encrypted before persistence, with `SECRET_ENCRYPTION_KEY` controlling encryption.
   - The `app/api/secrets/*` routes expose this as a service-scoped API, implying per-integration credential isolation.

7. **Provider/plugin architecture**
   - `lib/providers/provider.ts`, `registry.ts`, `catalog.ts`, and `builtin.ts` indicate a **pluggable provider model**.
   - `app/api/connectors/route.ts` likely exposes the current provider inventory and connection metadata.
   - This is the extensibility boundary for adding new operational integrations without changing the core UI architecture.

8. **Real-time signal path**
   - `lib/realtime.ts` and `realtime/mock-stream-server.js` show a separate real-time feed mechanism over WebSockets.
   - The README’s `NEXT_PUBLIC_WS_URL` points the client to a websocket stream for live operational updates.
   - In the architecture diagram, this should be shown as a parallel live-data channel feeding the dashboard, separate from standard request/response API calls.

9. **Knowledge ingestion flow**
   - `lib/knowledge-ingestion.ts` plus `app/api/ingest/route.ts` and `app/ingest/page.tsx` form a dedicated ingestion pipeline.
   - The ingestion surface is separate from general dashboard activity, which suggests documents or source artifacts are processed into operational knowledge rather than treated as ordinary app data.

10. **Integration-specific subsystems**
   - **Telegram**: `lib/telegram/client.ts`, `store.ts`, and `app/api/telegram/bots/*` support bot CRUD, command management, and test-message execution.
   - **Ollama**: `lib/ollama/client.ts` and `app/api/ollama/models/route.ts` integrate with local or self-hosted model discovery.
   - **Wix**: `lib/wix/client.ts` and `app/api/wix/overview/route.ts` provide a separate integration path for Wix operational data.
   - These should be drawn as external service adapters behind the Next.js API layer.

11. **Operational metrics and widgets**
   - `lib/metrics.ts` and `lib/widgets.ts` suggest the dashboard composes and persists operational status into widget-friendly views.
   - The visual board is likely driven by server-provided metrics plus client-side widget state, rather than hardcoded content.
   - This is the key “presentation of state” layer in the architecture.

12. **Background/auxiliary execution**
   - The `scripts/` directory and `realtime/mock-stream-server.js` show the repo includes **non-web runtime helpers**.
   - The Telegram runner scripts imply a separate polling/automation process that lives outside the Next.js request lifecycle.
   - In the diagram, these should be shown as worker/runner processes that interact with the APIs and external services independently.

13. **Deployment and runtime**
   - The app is deployed on **Vercel**, with `.github/workflows/deploy-vercel.yml` handling CI/CD.
   - `vercel.json` and the App Router structure indicate the web/API layer is serverless-friendly.
   - Runtime configuration comes from environment variables in `.env.example`, including Supabase credentials, websocket URL, encryption key, and admin token.

14. **How the pieces fit together**
   - Browser UI → Next.js App Router pages/components → API routes → service adapters / Supabase / external systems.
   - Real-time updates bypass normal HTTP via WebSockets into the dashboard.
   - Long-running or device-specific automation lives in scripts/runner processes, not inside the page request cycle.

Main entry points: [`app/page.tsx`](https://github.com/bluenot3/fus3/blob/main/app/page.tsx) (Command center), [`components/command-center-shell.tsx`](https://github.com/bluenot3/fus3/blob/main/components/command-center-shell.tsx) (Shell components), [`components/command-palette.tsx`](https://github.com/bluenot3/fus3/blob/main/components/command-palette.tsx) (Command palette), [`app/api/connectors/route.ts`](https://github.com/bluenot3/fus3/blob/main/app/api/connectors/route.ts) (Connectors API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_app_page["Command center<br/>next page<br/>[page.tsx]"]
  node_app_ingest_page["Ingest workspace<br/>next page<br/>[page.tsx]"]
  node_app_wix_page["Wix console<br/>next page<br/>[page.tsx]"]
  node_shells["Shell components<br/>ui shells"]
  node_palette["Command palette<br/>interaction"]
  node_widgets["Operational widgets<br/>ui widgets"]
end

subgraph group_api["API boundary"]
  node_connectors_api["Connectors API<br/>route handler<br/>[route.ts]"]
  node_metrics_api["Metrics API<br/>route handler<br/>[route.ts]"]
  node_secrets_api["Secrets API<br/>route handlers<br/>[route.ts]"]
  node_ingest_api["Ingest API<br/>route handler<br/>[route.ts]"]
  node_telegram_api["Telegram API<br/>route handlers<br/>[route.ts]"]
  node_ollama_api["Ollama API<br/>route handler<br/>[route.ts]"]
  node_wix_api["Wix overview<br/>route handler<br/>[route.ts]"]
  node_exports_api["Export jobs<br/>route handler<br/>[route.ts]"]
end

subgraph group_core["Core services"]
  node_ingestion_core["Ingestion core<br/>pipeline"]
  node_metrics_core["Metrics store<br/>state logic<br/>[metrics.ts]"]
  node_secrets_core["Secrets manager<br/>crypto/state<br/>[manager.ts]"]
  node_providers_core["Provider registry<br/>plugin system<br/>[registry.ts]"]
  node_realtime_core(("Realtime stream<br/>ws client<br/>[realtime.ts]"))
  node_supabase_core[("Supabase store<br/>database client<br/>[server.ts]")]
  node_telegram_core["Telegram client<br/>integration adapter<br/>[client.ts]"]
  node_ollama_core["Ollama client<br/>integration adapter<br/>[client.ts]"]
  node_wix_core["Wix client<br/>integration adapter<br/>[client.ts]"]
end

subgraph group_runtime["Auxiliary runtime"]
  node_runner_scripts["Runner scripts<br/>worker tools"]
  node_mock_ws(("Mock stream<br/>ws server"))
  node_deployment["Vercel deploy<br/>ci/cd<br/>[vercel.json]"]
end

node_app_page -->|"renders"| node_shells
node_app_ingest_page -->|"renders"| node_shells
node_app_wix_page -->|"renders"| node_shells
node_shells -->|"uses"| node_palette
node_shells -->|"composes"| node_widgets
node_app_page -->|"requests"| node_metrics_api
node_app_page -->|"requests"| node_connectors_api
node_app_page -->|"requests"| node_secrets_api
node_app_ingest_page -->|"requests"| node_ingest_api
node_app_wix_page -->|"requests"| node_wix_api
node_palette -->|"invokes"| node_connectors_api
node_palette -->|"invokes"| node_telegram_api
node_palette -->|"invokes"| node_exports_api
node_metrics_api -->|"reads"| node_metrics_core
node_metrics_core -->|"persists"| node_supabase_core
node_secrets_api -->|"uses"| node_secrets_core
node_secrets_core -->|"persists"| node_supabase_core
node_ingest_api -->|"uses"| node_ingestion_core
node_ingestion_core -->|"stores"| node_supabase_core
node_providers_core -->|"backs"| node_connectors_api
node_telegram_api -->|"uses"| node_telegram_core
node_ollama_api -->|"uses"| node_ollama_core
node_wix_api -->|"uses"| node_wix_core
node_widgets -->|"reads"| node_metrics_core
node_realtime_core -->|"updates"| node_app_page
node_mock_ws -->|"emulates"| node_realtime_core
node_runner_scripts -->|"calls"| node_telegram_api
node_deployment -->|"hosts"| node_app_page
node_deployment -->|"hosts"| node_connectors_api

click node_app_page "https://github.com/bluenot3/fus3/blob/main/app/page.tsx"
click node_app_ingest_page "https://github.com/bluenot3/fus3/blob/main/app/ingest/page.tsx"
click node_app_wix_page "https://github.com/bluenot3/fus3/blob/main/app/wix/page.tsx"
click node_shells "https://github.com/bluenot3/fus3/blob/main/components/command-center-shell.tsx"
click node_palette "https://github.com/bluenot3/fus3/blob/main/components/command-palette.tsx"
click node_widgets "https://github.com/bluenot3/fus3/blob/main/components/operational-widgets.tsx"
click node_connectors_api "https://github.com/bluenot3/fus3/blob/main/app/api/connectors/route.ts"
click node_metrics_api "https://github.com/bluenot3/fus3/blob/main/app/api/metrics/route.ts"
click node_secrets_api "https://github.com/bluenot3/fus3/blob/main/app/api/secrets/route.ts"
click node_ingest_api "https://github.com/bluenot3/fus3/blob/main/app/api/ingest/route.ts"
click node_telegram_api "https://github.com/bluenot3/fus3/blob/main/app/api/telegram/bots/route.ts"
click node_ollama_api "https://github.com/bluenot3/fus3/blob/main/app/api/ollama/models/route.ts"
click node_wix_api "https://github.com/bluenot3/fus3/blob/main/app/api/wix/overview/route.ts"
click node_exports_api "https://github.com/bluenot3/fus3/blob/main/app/api/exports/[jobId]/route.ts"
click node_ingestion_core "https://github.com/bluenot3/fus3/blob/main/lib/knowledge-ingestion.ts"
click node_metrics_core "https://github.com/bluenot3/fus3/blob/main/lib/metrics.ts"
click node_secrets_core "https://github.com/bluenot3/fus3/blob/main/lib/secrets/manager.ts"
click node_providers_core "https://github.com/bluenot3/fus3/blob/main/lib/providers/registry.ts"
click node_realtime_core "https://github.com/bluenot3/fus3/blob/main/lib/realtime.ts"
click node_supabase_core "https://github.com/bluenot3/fus3/blob/main/lib/supabase/server.ts"
click node_telegram_core "https://github.com/bluenot3/fus3/blob/main/lib/telegram/client.ts"
click node_ollama_core "https://github.com/bluenot3/fus3/blob/main/lib/ollama/client.ts"
click node_wix_core "https://github.com/bluenot3/fus3/blob/main/lib/wix/client.ts"
click node_runner_scripts "https://github.com/bluenot3/fus3/blob/main/scripts/telegram-polling-runner.js"
click node_mock_ws "https://github.com/bluenot3/fus3/blob/main/realtime/mock-stream-server.js"
click node_deployment "https://github.com/bluenot3/fus3/blob/main/vercel.json"

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_app_page,node_app_ingest_page,node_app_wix_page,node_shells,node_palette,node_widgets toneBlue
class node_connectors_api,node_metrics_api,node_secrets_api,node_ingest_api,node_telegram_api,node_ollama_api,node_wix_api,node_exports_api toneAmber
class node_ingestion_core,node_metrics_core,node_secrets_core,node_providers_core,node_realtime_core,node_supabase_core,node_telegram_core,node_ollama_core,node_wix_core toneMint
class node_runner_scripts,node_mock_ws,node_deployment toneRose
```

## Components

### UI surfaces

Primary Next.js pages and shell components for the command-center experience.

- [Command center](https://github.com/bluenot3/fus3/blob/main/app/page.tsx): next page · Main dashboard entry point for operational control. · `app/page.tsx`
- [Ingest workspace](https://github.com/bluenot3/fus3/blob/main/app/ingest/page.tsx): next page · Dedicated knowledge-ingestion surface. · `app/ingest/page.tsx`
- [Wix console](https://github.com/bluenot3/fus3/blob/main/app/wix/page.tsx): next page · Dedicated Wix operations surface. · `app/wix/page.tsx`
- [Shell components](https://github.com/bluenot3/fus3/blob/main/components/command-center-shell.tsx): ui shells · Command-center, ingest, Wix, and mobile layouts that compose the operational UI. · `components/command-center-shell.tsx`
- [Command palette](https://github.com/bluenot3/fus3/blob/main/components/command-palette.tsx): interaction · Keyboard-driven action launcher for dashboard workflows. · `components/command-palette.tsx`
- [Operational widgets](https://github.com/bluenot3/fus3/blob/main/components/operational-widgets.tsx): ui widgets · Widget layer that presents metrics and state in board form. · `components/operational-widgets.tsx`

### API boundary

Route handlers that expose backend capabilities to the UI and automation.

- [Connectors API](https://github.com/bluenot3/fus3/blob/main/app/api/connectors/route.ts): route handler · Provider discovery and registration boundary. · `app/api/connectors/route.ts`
- [Metrics API](https://github.com/bluenot3/fus3/blob/main/app/api/metrics/route.ts): route handler · Operational telemetry endpoint. · `app/api/metrics/route.ts`
- [Secrets API](https://github.com/bluenot3/fus3/blob/main/app/api/secrets/route.ts): route handlers · Credential CRUD and per-service secret management. · `app/api/secrets/route.ts`
- [Ingest API](https://github.com/bluenot3/fus3/blob/main/app/api/ingest/route.ts): route handler · Knowledge and content intake endpoint. · `app/api/ingest/route.ts`
- [Telegram API](https://github.com/bluenot3/fus3/blob/main/app/api/telegram/bots/route.ts): route handlers · Bot management, commands, and test messaging endpoints. · `app/api/telegram/bots/route.ts`
- [Ollama API](https://github.com/bluenot3/fus3/blob/main/app/api/ollama/models/route.ts): route handler · Model discovery endpoint for local or remote Ollama backends. · `app/api/ollama/models/route.ts`
- [Wix overview](https://github.com/bluenot3/fus3/blob/main/app/api/wix/overview/route.ts): route handler · Wix-specific operational summary endpoint. · `app/api/wix/overview/route.ts`
- [Export jobs](https://github.com/bluenot3/fus3/blob/main/app/api/exports/[jobId]/route.ts): route handler · Job status and retrieval endpoint for exports. · `app/api/exports/[jobId]/route.ts`

### Core services

Shared server-side logic, state, and integration adapters.

- [Ingestion core](https://github.com/bluenot3/fus3/blob/main/lib/knowledge-ingestion.ts): pipeline · Shared knowledge-ingestion logic. · `lib/knowledge-ingestion.ts`
- [Metrics store](https://github.com/bluenot3/fus3/blob/main/lib/metrics.ts): state logic · Operational metrics aggregation and widget shaping. · `lib/metrics.ts`
- [Secrets manager](https://github.com/bluenot3/fus3/blob/main/lib/secrets/manager.ts): crypto/state · Encrypts and manages persisted secrets. · `lib/secrets/manager.ts`
- [Provider registry](https://github.com/bluenot3/fus3/blob/main/lib/providers/registry.ts): plugin system · Pluggable provider catalog and registry for integrations. · `lib/providers/registry.ts`
- [Realtime stream](https://github.com/bluenot3/fus3/blob/main/lib/realtime.ts): ws client · WebSocket feed for live operational updates. · `lib/realtime.ts`
- [Supabase store](https://github.com/bluenot3/fus3/blob/main/lib/supabase/server.ts): database client · Server-side persistence for durable operational data. · `lib/supabase/server.ts`
- [Telegram client](https://github.com/bluenot3/fus3/blob/main/lib/telegram/client.ts): integration adapter · Client and store for Telegram bot operations. · `lib/telegram/client.ts`
- [Ollama client](https://github.com/bluenot3/fus3/blob/main/lib/ollama/client.ts): integration adapter · Adapter for Ollama model discovery. · `lib/ollama/client.ts`
- [Wix client](https://github.com/bluenot3/fus3/blob/main/lib/wix/client.ts): integration adapter · Adapter for Wix operational data. · `lib/wix/client.ts`

### Auxiliary runtime

Non-web processes and deployment/runtime support.

- [Runner scripts](https://github.com/bluenot3/fus3/blob/main/scripts/telegram-polling-runner.js): worker tools · Telegram polling and automation helpers that run outside the web request cycle. · `scripts/telegram-polling-runner.js`
- [Mock stream](https://github.com/bluenot3/fus3/blob/main/realtime/mock-stream-server.js): ws server · Local realtime stream server for development and testing. · `realtime/mock-stream-server.js`
- [Vercel deploy](https://github.com/bluenot3/fus3/blob/main/vercel.json): ci/cd · Serverless deployment configuration and workflow. · `vercel.json`

## Connections

- Command center → Shell components: renders · The command-center page is assembled from shell components.
- Ingest workspace → Shell components: renders · The ingest workspace uses a dedicated shell.
- Wix console → Shell components: renders · The Wix surface is composed through its command-center shell.
- Shell components → Command palette: uses · Shells expose keyboard-driven command execution.
- Shell components → Operational widgets: composes · Shells present operational widgets and status panes.
- Command center → Metrics API: requests · Dashboard data is fetched through the API boundary.
- Command center → Connectors API: requests · The command center discovers available connectors.
- Command center → Secrets API: requests · The UI manages service credentials through the secrets API.
- Ingest workspace → Ingest API: requests · Knowledge ingestion is initiated through the ingest route.
- Wix console → Wix overview: requests · Wix-specific status is fetched through its API route.
- Command palette → Connectors API: invokes · Palette actions can trigger provider discovery and setup.
- Command palette → Telegram API: invokes · Palette actions can manage Telegram bots and tests.
- Command palette → Export jobs: invokes · Palette actions can inspect export jobs.
- Metrics API → Metrics store: reads · Telemetry endpoints use shared metrics logic.
- Metrics store → Supabase store: persists · Metrics are stored durably in Supabase.
- Secrets API → Secrets manager: uses · Secret CRUD routes encrypt and manage credentials.
- Secrets manager → Supabase store: persists · Encrypted secrets are stored in Supabase.
- Ingest API → Ingestion core: uses · The ingest endpoint runs the shared pipeline.
- Ingestion core → Supabase store: stores · Ingestion state and results are persisted.
- Provider registry → Connectors API: backs · The connector API is powered by the provider registry.
- Telegram API → Telegram client: uses · Telegram routes operate through the Telegram client and store.
- Ollama API → Ollama client: uses · Model discovery is delegated to the Ollama adapter.
- Wix overview → Wix client: uses · Wix overview data comes from the Wix adapter.
- Operational widgets → Metrics store: reads · Widgets are shaped from operational metrics.
- Realtime stream → Command center: updates · Live websocket data feeds the dashboard.
- Mock stream → Realtime stream: emulates · Local mock stream serves as a development realtime source.
- Runner scripts → Telegram API: calls · Background Telegram runners interact with the API.
- Vercel deploy → Command center: hosts · The deployment target serves the Next.js app.
- Vercel deploy → Connectors API: hosts · Serverless deployment includes API routes.
