1. Unified End-to-End Architecture
Complete data flow from User to Backend, including Electron, React, and Resonance components.
flowchart TB
subgraph User["👤 USER"]
action["Clicks / Types / Navigates"]
end
subgraph Electron["⚡ ELECTRON SHELL"]
mainProc["main.ts
Main Process
• Window management
• IPC handlers
• HTTP requests"]
preload["preload.ts
Context Bridge
• Exposes window.grid
• Exposes window.ollama
• Exposes window.windowControls"]
end
subgraph React["⚛️ REACT RENDERER"]
app["App.tsx
Root Component"]
router["HashRouter
Client Routing"]
shell["AppShell
Layout + Nav"]
subgraph Pages["📄 PAGES (10)"]
dashboard["Dashboard"]
chat["ChatPage"]
rag["RagQuery"]
intel["Intelligence"]
cognitive["Cognitive"]
security["Security"]
obs["Observability"]
knowledge["Knowledge"]
end
subgraph DataLayer["🔄 DATA LAYER"]
query["TanStack Query
Caching + Fetching"]
gridClient["GridClient
GRID API calls"]
ollamaClient["OllamaClient
LLM calls"]
end
schema["Schema Layer
app.config.json
• Routes
• Endpoints
• Navigation"]
end
subgraph Backend["🖥️ BACKEND SERVICES"]
subgraph FastAPI["FastAPI :8000"]
health["/health
Health checks"]
ragAPI["/rag/query
RAG search"]
intelAPI["/api/v1/intelligence
Intelligence pipeline"]
cockpit["/api/v1/cockpit
Cognitive status"]
secAPI["/security
Security posture"]
end
subgraph Cognitive["🧠 COGNITIVE ENGINE"]
cogEngine["CognitiveEngine
Pattern detection"]
flowMgr["FlowManager
State orchestration"]
patterns["PatternManager
Recognition"]
end
subgraph Resonance["🔔 RESONANCE"]
actRes["ActivityResonance
Left-to-right comm"]
adsr["ADSR Envelope
Haptic feedback"]
context["ContextProvider
Fast context"]
pathViz["PathVisualizer
Triage paths"]
end
ollama["Ollama :11434
Local LLM
• Chat streaming
• Model management"]
end
%% User Flow
action --> app
app --> router --> shell --> Pages
%% React Internal
Pages --> query
Pages --> schema
query --> gridClient
query --> ollamaClient
%% IPC Bridge
gridClient -->|"window.grid.api()"| preload
ollamaClient -->|"window.ollama.chat()"| preload
preload -->|"ipcRenderer.invoke()"| mainProc
%% Backend Calls
mainProc -->|"HTTP GET/POST"| FastAPI
mainProc -->|"HTTP Streaming"| ollama
%% Backend Internal
cockpit --> cogEngine
cogEngine --> Resonance
actRes --> adsr
actRes --> context
actRes --> pathViz
intelAPI --> cogEngine
%% Response Flow (implied by bidirectional)
FastAPI -.->|"JSON Response"| mainProc
ollama -.->|"NDJSON Tokens"| mainProc
mainProc -.->|"IPC Event"| preload
preload -.->|"Callback"| DataLayer
DataLayer -.->|"State Update"| Pages
classDef user fill:#e1bee7,stroke:#7b1fa2,color:#000
classDef electron fill:#fff3e0,stroke:#ef6c00,color:#000
classDef react fill:#bbdefb,stroke:#1976d2,color:#000
classDef backend fill:#c8e6c9,stroke:#388e3c,color:#000
classDef cognitive fill:#ffe0b2,stroke:#f57c00,color:#000
classDef resonance fill:#b2dfdb,stroke:#00796b,color:#000
class User user
class Electron,mainProc,preload electron
class React,app,router,shell,Pages,DataLayer,schema react
class Backend,FastAPI,health,ragAPI,intelAPI,cockpit,secAPI,ollama backend
class Cognitive,cogEngine,flowMgr,patterns cognitive
class Resonance,actRes,adsr,context,pathViz resonance
2. Resonance Activity Flow
Sequence of events for processing cognitive activities with haptic-like feedback.
sequenceDiagram
participant C as Cognitive Page
participant G as GridClient
participant API as FastAPI
participant CE as CognitiveEngine
participant AR as ActivityResonance
participant CP as ContextProvider
participant PV as PathVisualizer
participant ADSR as ADSR Envelope
C->>G: Fetch cockpit status
G->>API: GET /api/v1/cockpit/status
API->>CE: process_cognitive_request()
CE->>AR: process_activity("cognitive", query)
par Left: Fast Context
AR->>CP: get_snapshot()
CP-->>AR: ContextSnapshot
and Right: Path Triage
AR->>PV: triage_paths()
PV-->>AR: PathTriage
end
AR->>ADSR: start_envelope()
ADSR-->>AR: EnvelopeMetrics
AR->>AR: _generate_feedback()
AR-->>CE: ResonanceFeedback
CE-->>API: CockpitStatus
API-->>G: JSON response
G-->>C: Render status cards
3. High-Level Architecture
Top-level view of Electron, Renderer, and Backend components.
flowchart TB
subgraph Electron["Electron Shell"]
main["main.ts
(Main Process)"]
preload["preload.ts
(Context Bridge)"]
end
subgraph Renderer["React Renderer"]
app["App.tsx"]
router["HashRouter"]
pages["Pages (10)"]
schema["Schema Layer"]
clients["API Clients"]
app --> router --> pages
pages --> schema
pages --> clients
end
subgraph Backend["Backend Services"]
grid["GRID API
:8000"]
ollama["Ollama
:11434"]
end
main --> preload
preload -->|window.grid| clients
preload -->|window.ollama| clients
clients -->|IPC| main
main -->|HTTP/NDJSON| grid
main -->|HTTP/Streaming| ollama
4. IPC Bridge Architecture
Detailed view of the secure IPC communication channel.
flowchart LR
subgraph Renderer["Renderer Process"]
gc["GridClient"]
oc["OllamaClient"]
wg["window.grid"]
wo["window.ollama"]
wc["window.windowControls"]
gc --> wg
oc --> wo
end
subgraph Preload["preload.ts"]
cb["contextBridge"]
ipc["ipcRenderer"]
end
subgraph Main["Main Process"]
handlers["IPC Handlers"]
http["HTTP Client"]
end
wg --> cb
wo --> cb
wc --> cb
cb --> ipc
ipc --> handlers
handlers --> http