zui/ARCHITECTURE.md

# Architecture Overview

## 1. Executive Summary

This document provides a high-level overview of the ZUI application's architecture, focusing on component organization, data flow, technology stack, and contribution guidelines for junior developers and AI agents.

## 2. Technology Stack

- **Frontend**: React 18, TypeScript, Vite, Tailwind CSS, Shadcn UI, Zustand (canvasStore), custom hooks, and canvas rendering engine.
- **Backend**: Node.js 18, TypeScript, Express-like routing, Docker, and environment variable configuration.
- **Database/Storage**: In-memory state management with optional persistence via cacheRepository.
- **Testing**: Vitest, React Testing Library, and Jest-like utilities.

## 3. High-Level Structure

The workspace is divided into two primary directories:

- **frontend/**: Contains the React application, component library, pages, and styling.
- **backend/**: Contains server-side code, services, repositories, models, and middleware.

### 3.1 Frontend Modules

| Module | Purpose | Key Files |
|--------|---------|-----------|
| **canvas** | Core graph/canvas rendering, nodes, edges, and interactive graph features. | `src/app/canvas/*`, `src/components/graph/*`, `src/components/nodes/*` |
| **recollections** | Collection management, browsing, editing, and related UI. | `src/app/recollections/*`, `src/components/ui/*` |
| **kosmos** | Knowledge organization system, settings, and user preferences. | `src/app/kosmos/*` |
| **layout** | Layout and navigation components shared across pages. | `src/app/recollections/layout/*` |
| **components** | Reusable UI components (buttons, dialogs, avatars, etc.). | `src/components/ui/*` |
| **hooks** | Custom React hooks for state, effects, and utilities. | `src/hooks/*` |
| **lib** | Shared utilities, types, and low-level helpers. | `src/lib/*` |

### 3.2 Backend Modules

| Module | Purpose | Key Files |
|--------|---------|-----------|
| **services** | Business logic, external API interactions, and complex computations. | `backend/src/services/*` |
| **repositories** | Data access abstraction, caching, and persistence. | `backend/src/repositories/*` |
| **models** | TypeScript interfaces and type definitions for domain objects. | `backend/src/models/*` |
| **routes** | HTTP route definitions and controllers. | `backend/src/routes/*` |
| **middleware** | Request processing pipeline (e.g., rate limiting, authentication). | `backend/src/middleware/*` |
| **index.ts** | Application entry point that composes services, routes, and middleware. | `backend/src/index.ts` |

## 4. Data Flow

1. **User Interaction** (React components) → dispatches actions → updates local state (Zustand) → triggers re-render.
2. **State Changes** may trigger async calls to **services** (frontend) → which call **backend APIs** → responses are cached via **cacheRepository**.
3. **Backend** processes requests via **routes**, applies **middleware**, interacts with **repositories** and **models**, and returns JSON responses.
4. **Caching** layer reduces repeated expensive computations or DB queries, improving performance.

## 5. Component Interaction Patterns

- **Container Components** (e.g., `CanvasPage`, `RecollectionPage`) manage layout and state provision.
- **Presentational Components** (e.g., `TreeBrowser`, `AgentNode`) focus on UI rendering only.
- **Custom Hooks** encapsulate logic (e.g., `useResizeHeight`, `useStreamingContent`) and are reused across components.
- **Context Providers** (`KosmosContext`, `RecollectionSidebarContext`) supply global state to deeply nested component trees.

## 6. Extensibility & Plug‑in Architecture

- **Node Types** are registered via `nodeRegistry.ts` and extended through descriptor files.
- **New node types** can be added by creating a descriptor, implementing rendering logic, and registering it in `registerBuiltinNodes.tsx`.
- **Extensibility points** are documented in `NODE_TYPE_EXTENSIBILITY_PROPOSAL.md`.

## 7. Performance Considerations

- **Large Render Trees**: `CanvasPage` and `RecollectionPage` handle thousands of nodes; memoization (`useMemo`, `useCallback`) and lazy loading are essential.
- **State Updates**: Prefer granular state updates in `canvasStore` to avoid full tree re-renders.
- **Code Splitting**: Dynamic imports are used for heavy modules (e.g., rendering views, graph utilities).

## 8. Contribution Workflow

1. Fork the repository and clone the workspace.
2. Install dependencies: `pnpm install` (or `npm ci`).
3. Run the dev server: `pnpm dev` (frontend) and `pnpm start` (backend).
4. Create a feature branch: `git checkout -b feat/your-feature`.
5. Follow the **Coding Standards** (see `CONTRIBUTING.md` for details).
6. Submit a Pull Request with:
   - Descriptive title.
   - Linked issue(s).
   - Updated tests (if applicable).
   - Documentation updates (if relevant).
7. Code Review Checklist:
   - [ ] Readability: clear naming, minimal nesting.
   - [ ] Maintainability: extracted utilities, JSDoc, TypeScript typings.
   - [ ] Performance: no unnecessary re-renders, proper memoization.
   - [ ] Accessibility: semantic HTML, ARIA attributes.
   - [ ] Security: no hardcoded secrets, proper input validation.

## 9. Coding Standards

- **TypeScript**: Strict mode (`strict`, `noImplicitAny`, `noUnusedVars`).
- **Naming**: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
- **File Structure**: Feature‑first (`features/<feature>/`) or domain‑grouped (`src/app/recollections/...`).
- **Documentation**: JSDoc for all public APIs, TSDoc for types, and inline comments for complex logic.
- **Formatting**: Prettier configured via `frontend/prettier.config.cjs`.

## 10. Quick Reference for AI Agents

- **Key Entry Points**: `frontend/src/main.tsx`, `backend/src/index.ts`.
- **State Management**: `src/lib/graph/state.ts`, `src/app/canvas/canvasStore.*`.
- **Routing**: `backend/src/routes/agentRoutes.ts`.
- **Caching**: `backend/src/repositories/cacheRepository.ts`.
- **Performance Hotspots**: `CanvasPage.tsx`, `RecollectionPage.tsx`, large utility functions in `src/lib/*`.

*This overview is intended to serve as a living document; future sections will expand on each module, performance audit findings, and junior developer quickstart guides.*