# 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).

## Project layout

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

---

## Run locally (dev)

**Frontend only:**

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

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

```bash
# 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

```bash
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. |

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.

---

## 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. |

---

## Backend API (no DB)

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

---

## Agent node (local LLM or OpenAI)

The **Agent** node uses an OpenAI-compatible API. You can use:

**1. Local LLM (e.g. LM Studio)**

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:

   ```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
   ```

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

**2. OpenAI**

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

**Env summary (backend)**

| 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. |