# halo-dev/upage architecture

> Architecture diagram of the GitHub repository halo-dev/upage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/halo-dev/upage
- Repository: https://github.com/halo-dev/upage

## Overview

1. **Repository shape**
   This is a single TypeScript monorepo centered on the UPage application, with the main product in `app/` and a separate `docs/` site for user/developer documentation. The runtime app is a React Router “framework mode” application with explicit server/client entry points and route-based API handlers.

2. **Primary product boundary**
   UPage is an AI-assisted visual web builder. The core user loop is: authenticate, start or resume a chat, describe a website or page, let the model generate/update structured page content, then review and edit it visually. The architecture is built around this chat-to-page-generation pipeline rather than a generic CRUD app.

3. **Client-side presentation layer**
   The browser UI is split into focused subsystems under `app/.client/components/`:  
   - `chat/` for conversation, tool output, prompts, usage, and deployment status  
   - `editor/` and `webbuilder/` for live page editing and preview  
   - `header/`, `sidebar/`, `layouts/`, and `ui/` for shell/navigation  
   - `upage/` for share/landing views  
   These components are driven by hooks and stores instead of keeping all state local to the UI.

4. **State and interaction model**
   Client state is organized in `app/.client/stores/` and `app/.client/hooks/`. The stores track chat, editor, pages, previews, deployment connections, settings, and sidebar state. Hooks such as `useChatEntries`, `useProject`, `useChatMessage`, and `useEditorCommands` connect UI actions to server APIs and derived runtime state.

5. **Server-side AI orchestration**
   The AI pipeline lives under `app/.server/llm/`. This is where prompts are prepared, context is selected, messages are streamed, and page-generation agents are executed. The flow includes:
   - preparation and context selection
   - model execution and streaming
   - agent logic for page building and drafting
   - structured message handling and page snapshot generation
   - tools and optional actions used by the agent
   This layer is the heart of the product: it converts natural language and references into a structured page model and incremental UI updates.

6. **Model/provider abstraction**
   `app/.server/modules/llm/` provides a provider-agnostic layer over many model backends. The repo includes adapters for OpenAI-compatible services and multiple hosted/local providers such as Anthropic, Google, Groq, Mistral, Ollama, OpenRouter, DeepSeek, and others. This abstraction lets the same page-builder workflow run against different default, minor, and vision models.

7. **Structured page runtime**
   `app/.client/runtime/` and related protocol files define the internal message/page protocol used between model output, runtime actions, and the visual editor. This layer normalizes page events, materializes page actions, and coordinates page changes so the UI can update incrementally instead of re-rendering from raw text alone.

8. **Data persistence and domain services**
   Persistent data is handled by Prisma (`prisma/schema.prisma`, migrations) and service modules in `app/.server/service/`. The domain services cover chats, messages, projects, pages, sections, assets, deployments, user settings, and connection settings. This is the authoritative backend boundary for app data, separate from the AI orchestration layer.

9. **File and asset handling**
   Uploaded references and generated assets are managed through `app/.server/service/asset-manager.ts`, upload routes, and storage providers under `app/.server/storage/`. The README’s Docker setup makes `/app/storage` a required persistent volume so image references can be reused across chat turns without repeatedly re-sending base64 payloads.

10. **Authentication and external integrations**
   Auth is routed through Logto-related endpoints and services. The app also integrates with deployment and hosting providers through dedicated modules and routes for GitHub, Netlify, Vercel, and 1Panel. These integrations support connecting accounts, pushing generated code, deploying sites, and querying deployment status.

11. **API surface**
   `app/routes/api/` is the server boundary exposed to the client. It includes endpoints for chat, deployments, design-system content, enhancer, project export/files, uploads, auth, health, and each deployment provider. The UI talks to these endpoints to manage chat sessions, fetch/generated page artifacts, and trigger external actions.

12. **Deployment and operations**
   The repo is built for containerized deployment. The root includes Dockerfiles, docker-compose configs, and GitHub Actions workflows for CI and image publishing. The runtime expects persistent directories for data, logs, and storage, reflecting that the app is stateful across conversations and generated assets.

13. **Docs and supporting tooling**
   `docs/` is a separate Docusaurus site for product and deployment documentation. The repository also includes tests alongside most major subsystems, which helps validate the chat/runtime protocol, editor behavior, and service logic that underpin the architecture.

Main entry points: [`app/.client/stores`](https://github.com/halo-dev/upage/blob/main/app/.client/stores) (Client state), [`app/.server/service`](https://github.com/halo-dev/upage/blob/main/app/.server/service) (Domain services), [`app`](https://github.com/halo-dev/upage/tree/main/app) (Framework app), [`app/.client/components/chat`](https://github.com/halo-dev/upage/blob/main/app/.client/components/chat) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_client["Client app"]
  node_n_routes["Framework app<br/>react-router app"]
  node_n_client_ui["UI shells<br/>presentation<br/>[components]"]
  node_n_chat_ui["Chat UI<br/>conversation UI<br/>[chat]"]
  node_n_editor_ui["Editor UI<br/>visual editor<br/>[editor]"]
  node_n_runtime["Page runtime<br/>client protocol<br/>[runtime]"]
  node_n_state["Client state<br/>stores/hooks<br/>[stores]"]
end

subgraph group_g_server["Server app"]
  node_n_server_llm["LLM pipeline<br/>ai orchestration<br/>[llm]"]
  node_n_model_mgr["Model adapters<br/>provider abstraction<br/>[llm]"]
  node_n_domain["Domain services<br/>service layer<br/>[service]"]
  node_n_storage["Storage layer<br/>asset storage<br/>[storage]"]
  node_n_prisma[("Database schema<br/>persistence<br/>[schema.prisma]")]
end

subgraph group_g_api["API routes"]
  node_n_api_chat["Chat API<br/>route handlers"]
  node_n_api_integrations["Integration API<br/>route handlers"]
  node_n_api_project["Project API<br/>route handlers"]
  node_n_api_upload["Upload API<br/>route handlers"]
  node_n_api_design["Design API<br/>route handlers"]
  node_n_api_auth["Auth API<br/>route handlers"]
end

subgraph group_g_docs["Docs site"]
  node_n_docs_site["Docs site<br/>docusaurus site"]
end

subgraph group_g_ops["Ops & deployment"]
  node_n_ops["Deploy ops<br/>container/ci"]
end

node_n_routes -->|"renders"| node_n_client_ui
node_n_routes -->|"hosts"| node_n_chat_ui
node_n_routes -->|"hosts"| node_n_editor_ui
node_n_chat_ui -->|"reads/writes"| node_n_state
node_n_editor_ui -->|"reads/writes"| node_n_state
node_n_chat_ui -->|"formats"| node_n_runtime
node_n_editor_ui -->|"applies"| node_n_runtime
node_n_state -->|"calls"| node_n_api_chat
node_n_state -->|"calls"| node_n_api_project
node_n_state -->|"uploads"| node_n_api_upload
node_n_state -->|"fetches"| node_n_api_design
node_n_api_chat -->|"invokes"| node_n_server_llm
node_n_server_llm -->|"selects model"| node_n_model_mgr
node_n_server_llm -->|"reads/writes"| node_n_domain
node_n_domain -->|"persists"| node_n_prisma
node_n_domain -->|"stores assets"| node_n_storage
node_n_api_upload -->|"writes"| node_n_storage
node_n_api_auth -->|"authenticates"| node_n_domain
node_n_api_integrations -->|"integrates"| node_n_domain
node_n_api_project -->|"exports"| node_n_domain
node_n_docs_site -.->|"documents"| node_n_ops
node_n_ops -.->|"packages"| node_n_routes

click node_n_routes "https://github.com/halo-dev/upage/tree/main/app"
click node_n_client_ui "https://github.com/halo-dev/upage/blob/main/app/.client/components"
click node_n_chat_ui "https://github.com/halo-dev/upage/blob/main/app/.client/components/chat"
click node_n_editor_ui "https://github.com/halo-dev/upage/blob/main/app/.client/components/editor"
click node_n_runtime "https://github.com/halo-dev/upage/blob/main/app/.client/runtime"
click node_n_state "https://github.com/halo-dev/upage/blob/main/app/.client/stores"
click node_n_server_llm "https://github.com/halo-dev/upage/blob/main/app/.server/llm"
click node_n_model_mgr "https://github.com/halo-dev/upage/blob/main/app/.server/modules/llm"
click node_n_domain "https://github.com/halo-dev/upage/blob/main/app/.server/service"
click node_n_storage "https://github.com/halo-dev/upage/blob/main/app/.server/storage"
click node_n_prisma "https://github.com/halo-dev/upage/blob/main/prisma/schema.prisma"
click node_n_api_chat "https://github.com/halo-dev/upage/tree/main/app/routes/api/chat"
click node_n_api_integrations "https://github.com/halo-dev/upage/tree/main/app/routes/api"
click node_n_api_project "https://github.com/halo-dev/upage/tree/main/app/routes/api/project"
click node_n_api_upload "https://github.com/halo-dev/upage/tree/main/app/routes/api/upload"
click node_n_api_design "https://github.com/halo-dev/upage/tree/main/app/routes/api/design-system"
click node_n_api_auth "https://github.com/halo-dev/upage/tree/main/app/routes/api/auth"
click node_n_docs_site "https://github.com/halo-dev/upage/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_routes,node_n_client_ui,node_n_chat_ui,node_n_editor_ui,node_n_runtime,node_n_state toneBlue
class node_n_server_llm,node_n_model_mgr,node_n_domain,node_n_storage,node_n_prisma toneAmber
class node_n_api_chat,node_n_api_integrations,node_n_api_project,node_n_api_upload,node_n_api_design,node_n_api_auth toneMint
class node_n_docs_site toneRose
class node_n_ops toneIndigo
```

## Components

### Client app

Browser UI, state, and runtime for the visual builder.

- [Framework app](https://github.com/halo-dev/upage/tree/main/app): react-router app · React Router framework-mode application shell and route entrypoints. · `app`
- [UI shells](https://github.com/halo-dev/upage/blob/main/app/.client/components): presentation · Header, sidebar, layouts, and shared UI components for the app shell. · `app/.client/components`
- [Chat UI](https://github.com/halo-dev/upage/blob/main/app/.client/components/chat): conversation UI · Conversation panels, prompts, tool output, usage, and deployment status. · `app/.client/components/chat`
- [Editor UI](https://github.com/halo-dev/upage/blob/main/app/.client/components/editor): visual editor · Live page editor, preview, and web builder controls. · `app/.client/components/editor`
- [Page runtime](https://github.com/halo-dev/upage/blob/main/app/.client/runtime): client protocol · Message parsing, page actions, and incremental page-change coordination. · `app/.client/runtime`
- [Client state](https://github.com/halo-dev/upage/blob/main/app/.client/stores): stores/hooks · Client stores and hooks for chat, editor, pages, previews, and integrations. · `app/.client/stores`

### Server app

AI orchestration, persistence, storage, and domain services.

- [LLM pipeline](https://github.com/halo-dev/upage/blob/main/app/.server/llm): ai orchestration · Prompt prep, context selection, streaming, and page-building agents. · `app/.server/llm`
- [Model adapters](https://github.com/halo-dev/upage/blob/main/app/.server/modules/llm): provider abstraction · Provider-agnostic model manager and adapters for multiple LLM backends. · `app/.server/modules/llm`
- [Domain services](https://github.com/halo-dev/upage/blob/main/app/.server/service): service layer · Chats, projects, pages, sections, assets, deployments, and user settings. · `app/.server/service`
- [Storage layer](https://github.com/halo-dev/upage/blob/main/app/.server/storage): asset storage · Local and pluggable storage providers for uploaded and generated assets. · `app/.server/storage`
- [Database schema](https://github.com/halo-dev/upage/blob/main/prisma/schema.prisma): persistence · Prisma schema and migrations for app data model. · `prisma/schema.prisma`

### API routes

Route handlers exposed to the client and integrations.

- [Chat API](https://github.com/halo-dev/upage/tree/main/app/routes/api/chat): route handlers · Chat session, runtime, update, fork, delete, and metadata endpoints. · `app/routes/api/chat`
- [Integration API](https://github.com/halo-dev/upage/tree/main/app/routes/api): route handlers · Auth and provider routes for deployment and account connections. · `app/routes/api`
- [Project API](https://github.com/halo-dev/upage/tree/main/app/routes/api/project): route handlers · Project export, files, and project-level access endpoints. · `app/routes/api/project`
- [Upload API](https://github.com/halo-dev/upage/tree/main/app/routes/api/upload): route handlers · Asset upload endpoint used by the editor and chat flows. · `app/routes/api/upload`
- [Design API](https://github.com/halo-dev/upage/tree/main/app/routes/api/design-system): route handlers · Design system content and list endpoints used by the builder. · `app/routes/api/design-system`
- [Auth API](https://github.com/halo-dev/upage/tree/main/app/routes/api/auth): route handlers · Logto-backed authentication and user session endpoints. · `app/routes/api/auth`

### Docs site

Separate documentation site for users and contributors.

- [Docs site](https://github.com/halo-dev/upage/tree/main/docs): docusaurus site · Standalone documentation site for product, deployment, and contribution guides. · `docs`

### Ops & deployment

Containerization, CI, and runtime support files.

- **Deploy ops**: container/ci · Dockerfiles, compose files, GitHub Actions, and startup scripts.

## Connections

- Framework app → UI shells: renders · Application routes compose the shell and shared presentation components.
- Framework app → Chat UI: hosts · Chat route mounts the conversation experience.
- Framework app → Editor UI: hosts · Editor and web builder views are mounted from the route app.
- Chat UI → Client state: reads/writes · Chat components are driven by hooks and stores.
- Editor UI → Client state: reads/writes · Editor and builder components consume shared client state.
- Chat UI → Page runtime: formats · Chat UI displays structured messages and tool results.
- Editor UI → Page runtime: applies · Editor UI consumes page events and incremental page actions.
- Client state → Chat API: calls · Client hooks talk to chat session and runtime endpoints.
- Client state → Project API: calls · Project state is loaded and exported through API endpoints.
- Client state → Upload API: uploads · Client uploads assets and references through the upload route.
- Client state → Design API: fetches · Builder UI fetches design-system content and lists.
- Chat API → LLM pipeline: invokes · Chat runtime routes trigger AI preparation and streaming.
- LLM pipeline → Model adapters: selects model · The AI pipeline delegates execution to provider adapters.
- LLM pipeline → Domain services: reads/writes · Generated messages, snapshots, and page changes are persisted through services.
- Domain services → Database schema: persists · Domain services use Prisma-backed application data.
- Domain services → Storage layer: stores assets · Assets and references are stored via the storage providers.
- Upload API → Storage layer: writes · Uploads are saved to persistent storage.
- Auth API → Domain services: authenticates · Auth endpoints connect session state to user data services.
- Integration API → Domain services: integrates · Deployment and account connection routes proxy into domain services.
- Project API → Domain services: exports · Project file/export endpoints gather persisted page data.
- Docs site → Deploy ops: documents · Deployment docs explain the containerized runtime and workflows.
- Deploy ops → Framework app: packages · Docker and CI support the application runtime and release process.
