217 lines
9.2 KiB
Markdown
217 lines
9.2 KiB
Markdown
# Architecture Overview
|
|
|
|
## 1. Executive Summary
|
|
|
|
Zui is a node-based visual editor for composing configs, templates, variables, and AI-generated content. The frontend is a React 18 SPA backed by a thin Express API for AI agent calls. All graph data is persisted in `localStorage`; the backend is stateless.
|
|
|
|
---
|
|
|
|
## 2. Technology Stack
|
|
|
|
| Layer | Technology |
|
|
| --- | --- |
|
|
| Frontend framework | React 18, TypeScript (strict), Vite 7 |
|
|
| Graph canvas | `@xyflow/react` v12 (React Flow) |
|
|
| State management | Zustand 5 (command/reducer pattern) |
|
|
| Styling | Tailwind CSS + Shadcn UI (`@radix-ui/*`) |
|
|
| Rich text | BlockNote 0.36 with custom blocks |
|
|
| Templating | Nunjucks |
|
|
| Graph traversal | `graphology` + `graphology-traversal` |
|
|
| Routing | React Router v6 |
|
|
| Backend | Node.js 20+, TypeScript, Express 4 |
|
|
| AI SDK | Vercel AI SDK v4 + `@ai-sdk/openai` |
|
|
| Testing | Vitest, React Testing Library |
|
|
|
|
---
|
|
|
|
## 3. Project Structure
|
|
|
|
```text
|
|
frontend/src/
|
|
├── main.tsx # Entry: registers node types & config types, mounts app
|
|
├── app/
|
|
│ ├── canvas/ # CanvasPage, canvasStore (Zustand), canvasStore.test.ts
|
|
│ ├── kosmos/ # KosmosPage, sidebar, AI settings, KosmosContext
|
|
│ └── recollections/
|
|
│ ├── RecollectionsPage # Workspace list
|
|
│ ├── RecollectionLayout # Shared layout (sidebar + outlet)
|
|
│ ├── flux/ # Flux view (graph canvas)
|
|
│ ├── logos/ # Logos view (BlockNote rich text)
|
|
│ └── katalogos/ # Katalogos view (artifact gallery)
|
|
├── components/
|
|
│ ├── graph/ # AnimatedEdge, BaseNode, handles, keyboard shortcuts
|
|
│ ├── nodes/ # One folder per node type
|
|
│ └── ui/ # Shadcn primitives
|
|
├── hooks/ # useGraphStateWithHistory, useResizeHeight, …
|
|
└── lib/
|
|
└── graph/
|
|
├── nodeRegistry.ts # Mutable plugin registry
|
|
├── registerBuiltinNodes.tsx
|
|
├── nodeTypeBuilder.ts # Fluent builder for node descriptors
|
|
├── configTypes.ts # Output type registry (plantuml, markdown, wireframe)
|
|
├── rendering.ts # 3-step rendering pipeline contract
|
|
├── state.ts # Graph state types
|
|
└── canvasStore/ # Reducer + selectors
|
|
|
|
backend/src/
|
|
├── index.ts # Express app, CORS, routes, error handler
|
|
├── routes/agentRoutes.ts # POST /api/agent, POST /api/agent/stream
|
|
├── services/agentService.ts # LLM call logic (Vercel AI SDK)
|
|
├── repositories/cacheRepository.ts
|
|
├── models/index.ts
|
|
└── middleware/rateLimiter.ts
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Key Architectural Patterns
|
|
|
|
### 4.1 Command / Reducer Store (canvasStore)
|
|
|
|
The Zustand canvas store uses a pure reducer (`canvasStoreReducer`) with a discriminated union of `CanvasCommand` types. All mutations go through `dispatch(command)`. In dev mode every command is logged to the console.
|
|
|
|
The store has three slices:
|
|
|
|
- **`graph`** — nodes and edges (the React Flow state)
|
|
- **`path`** — trigger pulse for edge animation
|
|
- **`ui`** — renaming state, fullscreen node, pending connection
|
|
|
|
### 4.2 Delta-based Undo / Redo
|
|
|
|
`useGraphStateWithHistory` computes *inverse deltas* (only the nodes/edges that changed) rather than snapshotting the full graph. Maximum 100 history entries. Drag operations commit a pre-drag snapshot on `onNodeDragStop`.
|
|
|
|
### 4.3 Node Plugin Registry
|
|
|
|
Node types are registered via a mutable registry in `nodeRegistry.ts`. The built-ins are registered at app init from `registerBuiltinNodes.tsx`. Adding a new node type requires:
|
|
|
|
1. Implement a React component for the node.
|
|
2. Create a descriptor using `NodeTypeBuilder`.
|
|
3. Call `registerNodeType(descriptor)` — no edits to core code.
|
|
|
|
### 4.4 Fluent Builder for Node Descriptors
|
|
|
|
`NodeTypeBuilder` provides a type-safe method-chaining API (`idPrefix`, `withInputOutput`, `classification`, `allowedSourceTypes`, `help`, `menu`, `withFullscreen`, `sourceRenderingLogic`, …). Required fields are validated at `.build()`.
|
|
|
|
### 4.5 Three-Step Rendering Pipeline
|
|
|
|
Defined as an explicit contract in `rendering.ts`:
|
|
|
|
1. **Resolve** — source node (Config/Agent) produces `{ resolved, outputTypeId, reasoning? }`
|
|
2. **Render** — output type handler converts the resolved string (PlantUML → Kroki SVG, Markdown → HTML, Wireframe → SVG)
|
|
3. **Display** — the Rendering node shows an image viewport or scrollable HTML
|
|
|
|
### 4.6 Node Classification System
|
|
|
|
Four metaphorical classes drive the create menu grouping:
|
|
|
|
| Class | Node type | Metaphor |
|
|
| --- | --- | --- |
|
|
| `psyche` | Variable | source / input |
|
|
| `physis` | Data (CSV) | physical data |
|
|
| `pneuma` | Config / Render | transformation |
|
|
| `archon` | Agent | AI / LLM |
|
|
|
|
### 4.7 Recollections (Workspaces)
|
|
|
|
Each workspace (recollection) is stored in `localStorage`:
|
|
|
|
| Key | Content |
|
|
| --- | --- |
|
|
| `zui_platform_recollections` | Metadata index (id, name, icon, timestamps) |
|
|
| `zui_graph_<id>` | Flux graph (nodes + edges) |
|
|
| `zui_logos_<id>` | BlockNote rich text document |
|
|
| `zui_render_cache_<id>` | Rendered artifact cache |
|
|
|
|
Legacy key prefix `emanations` is migrated to `recollections` on first load.
|
|
|
|
### 4.8 User-configurable AI Connection
|
|
|
|
`KosmosContext` persists `aiConnection` (provider, baseURL, model, apiKey) in `localStorage` under `zui_ai_connection`. The Agent node forwards this to the backend with each request, so users can switch between OpenAI and local LLMs (LM Studio, Ollama) from the UI without env variable changes.
|
|
|
|
### 4.9 Diagram Rendering via Kroki
|
|
|
|
PlantUML diagrams are rendered by proxying to `https://kroki.io` via `/api/kroki/plantuml/svg`. This proxy is configured in both the Vite dev server and Nginx production config. Timeout: 15 seconds.
|
|
|
|
---
|
|
|
|
## 5. Data Flow
|
|
|
|
```text
|
|
User interaction
|
|
→ dispatch(CanvasCommand) [canvasStore reducer]
|
|
→ Zustand state update [graph / path / ui slices]
|
|
→ React re-render [React Flow nodes/edges]
|
|
|
|
Rendering node triggered
|
|
→ Resolve source node [Config/Agent → resolved string]
|
|
→ Render output type [plantuml/markdown/wireframe]
|
|
→ Kroki proxy (PlantUML) [GET /api/kroki/plantuml/svg]
|
|
→ Agent backend (AI) [POST /api/agent or /api/agent/stream]
|
|
→ Display artifact [image / HTML / SVG viewport]
|
|
|
|
Agent node (streaming)
|
|
→ POST /api/agent/stream [Express → agentService]
|
|
→ Vercel AI SDK streams SSE [backend → frontend]
|
|
→ useStreamingContent hook consumes [updates node data]
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Backend Architecture
|
|
|
|
The backend is intentionally thin and stateless. It has three responsibilities:
|
|
|
|
1. **Proxy AI calls** — forwards prompts to the configured LLM (OpenAI or OpenAI-compatible).
|
|
2. **Stream responses** — `POST /api/agent/stream` uses `pipeTextStreamToResponse` from the Vercel AI SDK.
|
|
3. **Health check** — `GET /health` for Docker/orchestration readiness probes.
|
|
|
|
The `InMemoryCache` and `rateLimiter` middleware are implemented but not yet wired into the agent routes.
|
|
|
|
---
|
|
|
|
## 7. Contribution Workflow
|
|
|
|
1. Fork the repository and clone locally.
|
|
2. Install dependencies: `cd frontend && npm install` and `cd backend && npm install`.
|
|
3. Run the dev servers (see README).
|
|
4. Create a feature branch: `git checkout -b feat/your-feature`.
|
|
5. Follow the Coding Standards (see [CONTRIBUTING.md](CONTRIBUTING.md)).
|
|
6. Submit a Pull Request with a descriptive title, linked issue(s), updated tests, and documentation changes if relevant.
|
|
|
|
### PR Review Checklist
|
|
|
|
- [ ] Readability: clear naming, minimal nesting
|
|
- [ ] TypeScript: no `any`, strict types throughout
|
|
- [ ] Performance: no unnecessary re-renders, proper memoization
|
|
- [ ] Accessibility: semantic HTML, ARIA attributes where needed
|
|
- [ ] Security: no hardcoded secrets, input validated at boundaries
|
|
|
|
---
|
|
|
|
## 8. Coding Standards
|
|
|
|
- **TypeScript**: strict mode (`strict`, `noImplicitAny`, `noUnusedLocals`).
|
|
- **Naming**: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
|
|
- **File structure**: domain-grouped under `src/app/<domain>/` and `src/components/<category>/`.
|
|
- **Formatting**: Prettier via `frontend/prettier.config.cjs`; line length ≤ 120.
|
|
- **Comments**: JSDoc for public APIs; inline only where logic is non-obvious.
|
|
|
|
---
|
|
|
|
## 9. Quick Reference for AI Agents
|
|
|
|
| Topic | Location |
|
|
| --- | --- |
|
|
| Entry point | `frontend/src/main.tsx` |
|
|
| Canvas store | `frontend/src/app/canvas/canvasStore.ts` |
|
|
| Store reducer | `frontend/src/app/canvas/canvasStoreReducer.ts` |
|
|
| Node registry | `frontend/src/lib/graph/nodeRegistry.ts` |
|
|
| Node builder | `frontend/src/lib/graph/nodeTypeBuilder.ts` |
|
|
| Rendering pipeline | `frontend/src/lib/graph/rendering.ts` |
|
|
| Built-in node registration | `frontend/src/lib/graph/registerBuiltinNodes.tsx` |
|
|
| AI settings context | `frontend/src/app/kosmos/KosmosContext.tsx` |
|
|
| Backend entry | `backend/src/index.ts` |
|
|
| Agent service | `backend/src/services/agentService.ts` |
|
|
|
|
*This document is a living reference; update it when architectural decisions change.*
|