How bluenot3/fus3 works
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: page.tsx Command center · command-center-shell.tsx Shell components · command-palette.tsx Command palette · route.ts Connectors API
Components 26
UI surfaces
Primary Next.js pages and shell components for the command-center experience.
- Command center · Main dashboard entry point for operational control.
app/page.tsx - Ingest workspace · Dedicated knowledge-ingestion surface.
app/ingest/page.tsx - Wix console · Dedicated Wix operations surface.
app/wix/page.tsx - Shell components · Command-center, ingest, Wix, and mobile layouts that compose the operational UI.
components/command-center-shell.tsx - Command palette · Keyboard-driven action launcher for dashboard workflows.
components/command-palette.tsx - Operational 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 · Provider discovery and registration boundary.
app/api/connectors/route.ts - Metrics API · Operational telemetry endpoint.
app/api/metrics/route.ts - Secrets API · Credential CRUD and per-service secret management.
app/api/secrets/route.ts - Ingest API · Knowledge and content intake endpoint.
app/api/ingest/route.ts - Telegram API · Bot management, commands, and test messaging endpoints.
app/api/telegram/bots/route.ts - Ollama API · Model discovery endpoint for local or remote Ollama backends.
app/api/ollama/models/route.ts - Wix overview · Wix-specific operational summary endpoint.
app/api/wix/overview/route.ts - Export jobs · 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 · Shared knowledge-ingestion logic.
lib/knowledge-ingestion.ts - Metrics store · Operational metrics aggregation and widget shaping.
lib/metrics.ts - Secrets manager · Encrypts and manages persisted secrets.
lib/secrets/manager.ts - Provider registry · Pluggable provider catalog and registry for integrations.
lib/providers/registry.ts - Realtime stream · WebSocket feed for live operational updates.
lib/realtime.ts - Supabase store · Server-side persistence for durable operational data.
lib/supabase/server.ts - Telegram client · Client and store for Telegram bot operations.
lib/telegram/client.ts - Ollama client · Adapter for Ollama model discovery.
lib/ollama/client.ts - Wix client · Adapter for Wix operational data.
lib/wix/client.ts
Auxiliary runtime
Non-web processes and deployment/runtime support.
- Runner scripts · Telegram polling and automation helpers that run outside the web request cycle.
scripts/telegram-polling-runner.js - Mock stream · Local realtime stream server for development and testing.
realtime/mock-stream-server.js - Vercel deploy · Serverless deployment configuration and workflow.
vercel.json
Connections 29
- 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.