zui/README.md

Zui

Node-based visual editor (React Flow) for composing configs, variables, templates, and AI-generated content. Three views per workspace: Flux (graph canvas), Logos (rich text), and Katalogos (artifact gallery). Optional Node.js backend for AI agent calls.

Project layout

zui/
├── frontend/               # React SPA (Vite, TypeScript)
│   ├── src/
│   │   ├── main.tsx            # Entry point: registers node/config types, mounts React
│   │   ├── app/
│   │   │   ├── canvas/         # Core graph editor (React Flow + Zustand)
│   │   │   ├── kosmos/         # Platform shell: sidebar, recollection list, AI settings
│   │   │   └── recollections/  # Logos (rich text), Flux (canvas), Katalogos (gallery)
│   │   ├── components/
│   │   │   ├── graph/          # AnimatedEdge, BaseNode, handles, keyboard shortcuts
│   │   │   ├── nodes/          # One folder per node type (agent, config, variable, …)
│   │   │   └── ui/             # Shadcn-based primitives
│   │   ├── hooks/              # Custom React hooks
│   │   └── lib/
│   │       └── graph/          # Registry, types, state, rendering pipeline, Nunjucks utils
│   ├── Dockerfile              # Multi-stage: Vite build → Nginx
│   ├── Dockerfile.dev          # Dev with hot reload
│   ├── nginx.conf
│   └── package.json
├── backend/                # Node.js/Express API
│   ├── src/
│   │   ├── index.ts            # Express entry: registers routes, CORS, error handler
│   │   ├── routes/agentRoutes.ts
│   │   ├── services/agentService.ts
│   │   ├── repositories/cacheRepository.ts
│   │   ├── models/index.ts
│   │   └── middleware/rateLimiter.ts
│   └── package.json
├── docs/
│   ├── ARCHITECTURE.md
│   ├── PERFORMANCE.md
│   ├── NODE_TYPE_EXTENSIBILITY_PROPOSAL.md
│   └── CODE_REVIEW_CHECKLIST.md
├── docker-compose.yml
└── .gitignore

Ignored by git: node_modules, dist, .env, .env.*. Local Docker overrides: docker-compose.override.yml (optional, not committed).

---

Run locally (dev)

Frontend only (no AI agent):

cd frontend && npm install && npm run dev
# → http://localhost:3000

Frontend + backend (for AI agent and health check):

# Terminal 1 – backend
cd backend && npm install && npm run dev
# → http://localhost:8080

# Terminal 2 – frontend
cd frontend && npm install && npm run dev
# → http://localhost:3000  (Vite proxies /api/* and /health to backend)

---

Run with Docker

docker compose up --build

• Frontend: http://localhost:3000 (Nginx; /api/* proxied to backend).
• Backend: http://localhost:8080 (Express).

Environment variables (backend service):

Variable	Default	Description
PORT	8080	Backend listen port.
CORS_ORIGIN	http://localhost:3000	Allowed origin for CORS.
AI_BASE_URL	(unset)	OpenAI-compatible base URL (local LLMs).
AI_MODEL	gpt-4o-mini	Model ID for the AI agent.
OPENAI_API_KEY	(unset)	Required when using OpenAI directly.

For self-hosting (e.g., Tailscale/HTTPS): set CORS_ORIGIN to your frontend URL and put Caddy or Nginx in front for TLS.

---

Scripts

Command	Description
cd frontend && npm run dev	Vite dev server (port 3000).
cd frontend && npm run build	Build frontend for production.
cd frontend && npm run preview	Preview production build.
cd frontend && npm run test	Run tests in watch mode (Vitest).
cd frontend && npm run test:run	Run tests once (CI).
cd backend && npm run dev	Backend with tsx --watch.
cd backend && npm start	Backend production run.
docker compose up --build	Run full stack in Docker.

---

Backend API

Method	Path	Body / Response
GET	/health	{ ok: true, timestamp: number } — health check for Docker/orchestration.
POST	/api/agent	Body { prompt, context?, contextNodes? } → { markdown } (one-shot).
POST	/api/agent/stream	Body { prompt, context?, contextNodes? } → SSE text stream (streaming).

---

Agent node (local LLM or OpenAI)

AI connection settings are configured directly in the UI — open the sidebar and go to AI Settings. You can switch between providers without restarting the server.

The backend reads its AI config from environment variables as a fallback:

Local LLM (e.g. LM Studio)

1. Install LM Studio, load a model, and start the local server (default: http://localhost:1234).

2. Set env vars (backend):

   export AI_BASE_URL=http://localhost:1234/v1
   export AI_MODEL=your-model-name   # optional; matches the name shown in LM Studio
   

OpenAI

export OPENAI_API_KEY=sk-...
export AI_MODEL=gpt-4o-mini   # optional; defaults to gpt-4o-mini

---

Contribute

• ARCHITECTURE.md — architecture overview, key patterns, module map
• CONTRIBUTING.md — coding standards, branch workflow, test commands
• PERFORMANCE_IMPROVEMENTS.md — bottleneck analysis and improvement plan
• docs/CODE_REVIEW_CHECKLIST.md — PR review checklist
• docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md — node plugin system design

Thank you for contributing!