fix: documentation
This commit is contained in:
105
ARCHITECTURE.md
Normal file
105
ARCHITECTURE.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user