How halo-dev/upage works
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: stores Client state · service Domain services · app Framework app · chat Chat UI
Components 19
Client app
Browser UI, state, and runtime for the visual builder.
- Framework app · React Router framework-mode application shell and route entrypoints.
app - UI shells · Header, sidebar, layouts, and shared UI components for the app shell.
app/.client/components - Chat UI · Conversation panels, prompts, tool output, usage, and deployment status.
app/.client/components/chat - Editor UI · Live page editor, preview, and web builder controls.
app/.client/components/editor - Page runtime · Message parsing, page actions, and incremental page-change coordination.
app/.client/runtime - Client state · 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 · Prompt prep, context selection, streaming, and page-building agents.
app/.server/llm - Model adapters · Provider-agnostic model manager and adapters for multiple LLM backends.
app/.server/modules/llm - Domain services · Chats, projects, pages, sections, assets, deployments, and user settings.
app/.server/service - Storage layer · Local and pluggable storage providers for uploaded and generated assets.
app/.server/storage - Database schema · Prisma schema and migrations for app data model.
prisma/schema.prisma
API routes
Route handlers exposed to the client and integrations.
- Chat API · Chat session, runtime, update, fork, delete, and metadata endpoints.
app/routes/api/chat - Integration API · Auth and provider routes for deployment and account connections.
app/routes/api - Project API · Project export, files, and project-level access endpoints.
app/routes/api/project - Upload API · Asset upload endpoint used by the editor and chat flows.
app/routes/api/upload - Design API · Design system content and list endpoints used by the builder.
app/routes/api/design-system - Auth API · Logto-backed authentication and user session endpoints.
app/routes/api/auth
Docs site
Separate documentation site for users and contributors.
- Docs site · Standalone documentation site for product, deployment, and contribution guides.
docs
Ops & deployment
Containerization, CI, and runtime support files.
- Deploy ops · Dockerfiles, compose files, GitHub Actions, and startup scripts.
Connections 22
- 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.