fix: improvements

2026-03-28 22:20:19 +01:00
parent cbd8f1568b
commit 223336c606
10 changed files with 506 additions and 249 deletions
--- a/README.md
+++ b/README.md
@@ -1,42 +1,61 @@
 # Zui

-Node-based editor (React Flow) for configs, variables, and rendering (PlantUML, Markdown, etc.). Optional Node.js backend API for demos or future features (e.g. todos CRUD).
+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

-```
-my-app/
-├── frontend/           # React app (Vite, TypeScript)
-│   ├── Dockerfile      # Multi-stage for prod (build → Nginx)
-│   ├── Dockerfile.dev  # Dev with hot reload
+```text
+zui/
+├── frontend/               # React SPA (Vite, TypeScript)
 │   ├── src/
-│   ├── public/
+│   │   ├── 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
-│   ├── Dockerfile
+├── backend/                # Node.js/Express API
 │   ├── src/
-│   │   └── index.js
+│   │   ├── 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
-├── .dockerignore
 └── .gitignore
 ```

-Ignored by git: `node_modules`, `dist`, `.env`, `.env.*` (see [.gitignore](.gitignore)). Local Docker overrides: `docker-compose.override.yml` (optional, not committed).
+Ignored by git: `node_modules`, `dist`, `.env`, `.env.*`. Local Docker overrides: `docker-compose.override.yml` (optional, not committed).

 ---

 ## Run locally (dev)

-**Frontend only:**
+**Frontend only** (no AI agent):

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

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

 ```bash
 # Terminal 1 – backend
@@ -45,7 +64,7 @@ cd backend && npm install && npm run dev

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

 ---
@@ -61,77 +80,74 @@ docker compose up --build

 Environment variables (backend service):

-| Variable     | Default                    | Description |
-|-------------|----------------------------|-------------|
-| `PORT`      | `8080`                     | Backend listen port. |
-| `CORS_ORIGIN` | `http://localhost:3000`  | Allowed origin for CORS. |
+| 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; put Caddy or Nginx in front for TLS if needed.
-
-**Dev with Docker (frontend hot reload):** use `frontend/Dockerfile.dev` and mount `./frontend` as a volume, or run `cd frontend && npm run dev` locally.
+For self-hosting (e.g., Tailscale/HTTPS): set `CORS_ORIGIN` to your frontend URL and put Caddy or Nginx in front for TLS.

 ---

 ## Scripts

-## Contribute
-
-For contribution guidelines, see:
-
- [ARCHITECTURE.md](ARCHITECTURE.md)
- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md)
- [QUICKSTART_FOR_JUNIORS.md](QUICKSTART_FOR_JUNIORS.md)
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_REVIEW_CHECKLIST.md](CODE_REVIEW_CHECKLIST.md)
-
-*Thank you for contributing!*
-
-| Command | Description |
-|--------|-------------|
-| `cd frontend && npm run dev` | Vite dev server. |
-| `cd frontend && npm run build` | Build frontend for production. |
-| `cd frontend && npm run preview` | Preview production build. |
-| `cd backend && npm run dev` | Backend with `--watch`. |
-| `cd backend && npm start` | Backend production run. |
-| `docker compose up --build` | Run frontend + backend in Docker. |
+| 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 (no DB)
+## Backend API

-| Method | Path | Description |
-|--------|------|-------------|
-| GET    | `/health`        | Health check (e.g. for Docker). |
-| POST   | `/api/agent`     | Run AI agent; body `{ "prompt", "context?", "contextNodes?" }` → `{ "markdown" }`. |
+| 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)

-The **Agent** node uses an OpenAI-compatible API. You can use:
+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.

-**1. Local LLM (e.g. LM Studio)**
+The backend reads its AI config from environment variables as a fallback:

-1. Install [LM Studio](https://lmstudio.ai/) and load a model.
-2. Start the local server: in LM Studio open the **Developer** tab and run the **Local Server** (default: `http://localhost:1234`).
-3. In the project root or `backend/`, set:
+### Local LLM (e.g. LM Studio)
+
+1. Install [LM Studio](https://lmstudio.ai/), load a model, and start the local server (default: `http://localhost:1234`).
+2. Set env vars (backend):

   ```bash
   export AI_BASE_URL=http://localhost:1234/v1
-   # Optional: set to the model name shown in LM Studio (e.g. the loaded model id). Default is "local-model".
-   export AI_MODEL=your-model-name
+   export AI_MODEL=your-model-name   # optional; matches the name shown in LM Studio
   ```

-4. Start the backend (`cd backend && npm run dev`). The Agent node will use your local model.
+### OpenAI

-**2. OpenAI**
+```bash
+export OPENAI_API_KEY=sk-...
+export AI_MODEL=gpt-4o-mini   # optional; defaults to gpt-4o-mini
+```

-Set `OPENAI_API_KEY` to your API key. The backend will use `gpt-4o-mini` unless you set `AI_MODEL`.
+---

-**Env summary (backend)**
+## Contribute

-| Variable | When to use | Description |
-|----------|--------------|-------------|
-| `AI_BASE_URL` | Local LLM (LM Studio, Ollama, etc.) | OpenAI-compatible base URL, e.g. `http://localhost:1234/v1`. |
-| `AI_MODEL` | Optional | Model id (for local: use the name shown in LM Studio; for OpenAI: e.g. `gpt-4o-mini`). |
-| `OPENAI_API_KEY` | OpenAI only | Your OpenAI API key. Not required when using `AI_BASE_URL` only. |
+- [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview, key patterns, module map
+- [CONTRIBUTING.md](CONTRIBUTING.md) — coding standards, branch workflow, test commands
+- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) — bottleneck analysis and improvement plan
+- [docs/CODE_REVIEW_CHECKLIST.md](docs/CODE_REVIEW_CHECKLIST.md) — PR review checklist
+- [docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md](docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md) — node plugin system design
+
+*Thank you for contributing!*