# alimomin-12/heliosprimer architecture

> Architecture diagram of the GitHub repository alimomin-12/heliosprimer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alimomin-12/heliosprimer
- Repository: https://github.com/alimomin-12/heliosprimer

## Overview

1. **Overall shape**
HeliosPrimer is a Next.js 16 App Router application that combines a browser UI, server route handlers, and a local SQLite persistence layer. The main architectural split is between the protected dashboard experience and the server-side API endpoints that handle auth, conversation state, provider connections, and AI execution.

2. **Route structure**
The `app/` directory is organized into a public entry point (`/`), a login flow (`/login`), and a protected dashboard segment under `app/(dashboard)`. Inside the dashboard are the main product surfaces: chat, provider connection management, conversation history, a dashboard overview, and an orchestrator changelog page.

3. **Authentication boundary**
Authentication is handled by NextAuth v5 through `app/api/auth/[...nextauth]/route.ts` and configured in `lib/auth.ts`. The app uses email magic-link sign-in, so the auth boundary sits entirely on the server. `types/next-auth.d.ts` suggests custom session/user typing is used across the app.

4. **Protected UI shell**
`app/(dashboard)/layout.tsx` and `components/layout/Sidebar.tsx` define the authenticated shell of the product. This is where the app likely enforces navigation between chat, history, and connection management, while `components/theme/*` handles theme selection and persistence at the UI layer.

5. **Chat execution path**
The chat UI in `app/(dashboard)/chat/page.tsx` talks to `app/api/chat/route.ts` for direct model interaction. This endpoint is the primary runtime path for a user message: it receives conversation context, resolves the configured provider/model, invokes the model adapter, and returns a streamed or incremental assistant response.

6. **Orchestration mode**
`app/api/orchestrate/route.ts` and `lib/ai/orchestrator.ts` implement the multi-model “master/slave” flow described in the README. The orchestrator is a separate server-side subsystem from direct chat: it coordinates planning, delegation to one or more models, and synthesis of final output, with intermediate steps exposed as conversation messages.

7. **Provider abstraction layer**
AI provider differences are isolated under `lib/ai/adapters/` and normalized through `lib/ai/types.ts` and `lib/ai/registry.ts`. This makes provider selection a data/config problem rather than a UI concern. The repo currently includes adapters for OpenAI, Gemini, DeepSeek, and Qwen, even though the README emphasizes OpenAI and Gemini.

8. **Conversation and connection APIs**
The app exposes dedicated server routes for CRUD-style state: `app/api/conversations/route.ts` and `app/api/conversations/[id]/route.ts` manage persisted chat sessions and messages, while `app/api/connections/route.ts` and `app/api/connections/test/route.ts` manage AI provider credentials and validation. This cleanly separates persistent product data from transient chat inference.

9. **Persistence layer**
`lib/prisma.ts` is the Prisma client singleton, and `prisma/schema.prisma` defines the data model backed by local SQLite. The database stores users, auth sessions/accounts, provider connections, conversations, messages, and orchestration configuration. That persistence boundary is central: UI state is minimal, while conversation history and connection settings are server-owned and durable.

10. **Secret handling**
`lib/encryption.ts` is a key architectural boundary because provider API keys are never stored in plaintext. The connect flow encrypts keys before saving them to SQLite, and the chat/orchestration flows decrypt them in memory only long enough to call the provider API. This means the AI keys are part of server-side protected state, not client state.

11. **Auxiliary capabilities**
`lib/fileProcessing.ts`, `lib/artifacts.ts`, and `lib/markdownRenderer.tsx` indicate the chat layer has support for richer message rendering and possibly file or artifact handling. These are supporting subsystems around the core conversation flow rather than primary application entry points.

12. **Environment and deployment assumptions**
The repo is designed for local-first development with SQLite (`prisma/dev.db`) and email magic-link delivery via a configurable SMTP provider or MailHog. The external service dependencies that materially affect architecture are NextAuth email delivery, provider LLM APIs, and the local database; there is no separate backend service beyond the Next.js server.

13. **Where the important boundaries are**
If you are drawing the architecture, the key boundaries are: browser UI vs. Next.js server routes, auth-gated dashboard vs. public login/landing pages, direct chat vs. orchestrated multi-model chat, and encrypted stored credentials vs. runtime-decrypted provider calls. Most of the system complexity lives in these server-side transitions rather than in the presentation layer.

Main entry points: [`components/layout/Sidebar.tsx`](https://github.com/alimomin-12/heliosprimer/blob/master/components/layout/Sidebar.tsx) (Sidebar), [`lib/prisma.ts`](https://github.com/alimomin-12/heliosprimer/blob/master/lib/prisma.ts) (Prisma), [`app/api/chat/route.ts`](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/chat/route.ts) (Chat API), [`app/api/connections/route.ts`](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/connections/route.ts) (Connections API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI surfaces"]
  node_node_app_root["App shell<br/>next app<br/>[layout.tsx]"]
  node_node_public_home["Landing<br/>public page<br/>[page.tsx]"]
  node_node_login["Login<br/>auth page<br/>[page.tsx]"]
  node_node_dashboard_layout["Dashboard shell<br/>protected layout<br/>[layout.tsx]"]
  node_node_sidebar["Sidebar<br/>nav component<br/>[Sidebar.tsx]"]
  node_node_theme["Theme UI<br/>ui support<br/>[ThemeProvider.tsx]"]
  node_node_chat_page["Chat<br/>dashboard page<br/>[page.tsx]"]
  node_node_connect_page["Connections<br/>dashboard page<br/>[page.tsx]"]
  node_node_history_page["History<br/>dashboard page<br/>[page.tsx]"]
  node_node_overview_page["Dashboard<br/>[page.tsx]"]
  node_node_changelog_page["Orchestrator log<br/>dashboard page<br/>[page.tsx]"]
end

subgraph group_group_api["Server routes"]
  node_node_auth_route["Auth API<br/>route handler<br/>[route.ts]"]
  node_node_chat_route["Chat API<br/>route handler<br/>[route.ts]"]
  node_node_connections_route["Connections API<br/>route handler<br/>[route.ts]"]
  node_node_conversations_route["Conversations API<br/>route handler<br/>[route.ts]"]
  node_node_orchestrate_route["Orchestrate API<br/>route handler<br/>[route.ts]"]
  node_node_dev_keys_route["Dev keys API<br/>route handler<br/>[route.ts]"]
end

subgraph group_group_ai["AI runtime"]
  node_node_orchestrator["Orchestrator<br/>ai coordinator<br/>[orchestrator.ts]"]
  node_node_registry["Model registry<br/>provider registry<br/>[registry.ts]"]
  node_node_adapters["Provider adapters<br/>ai adapters<br/>[openai.ts]"]
end

subgraph group_group_data["Data layer"]
  node_node_auth_lib["Auth config<br/>[auth.ts]"]
  node_node_encryption["Encryption<br/>secret handling<br/>[encryption.ts]"]
  node_node_prisma["Prisma<br/>db client<br/>[prisma.ts]"]
  node_node_schema[("SQLite schema<br/>data model<br/>[schema.prisma]")]
end

node_node_app_root -->|"serves"| node_node_public_home
node_node_app_root -->|"serves"| node_node_login
node_node_app_root -->|"hosts"| node_node_dashboard_layout
node_node_dashboard_layout -->|"contains"| node_node_sidebar
node_node_dashboard_layout -->|"wraps"| node_node_theme
node_node_sidebar -->|"navigates"| node_node_chat_page
node_node_sidebar -->|"navigates"| node_node_connect_page
node_node_sidebar -->|"navigates"| node_node_history_page
node_node_sidebar -->|"navigates"| node_node_overview_page
node_node_sidebar -->|"navigates"| node_node_changelog_page
node_node_login -->|"authenticates"| node_node_auth_route
node_node_auth_route -->|"configured by"| node_node_auth_lib
node_node_chat_page -->|"sends messages"| node_node_chat_route
node_node_chat_route -->|"resolves provider"| node_node_registry
node_node_chat_route -->|"loads secrets"| node_node_encryption
node_node_chat_route -->|"persists state"| node_node_conversations_route
node_node_connect_page -->|"manages"| node_node_connections_route
node_node_connections_route -->|"encrypts keys"| node_node_encryption
node_node_connections_route -->|"writes data"| node_node_prisma
node_node_history_page -->|"reads history"| node_node_conversations_route
node_node_orchestrate_route -->|"executes"| node_node_orchestrator
node_node_orchestrator -->|"delegates to"| node_node_registry
node_node_orchestrator -->|"loads secrets"| node_node_encryption
node_node_orchestrator -->|"records steps"| node_node_conversations_route
node_node_registry -->|"selects"| node_node_adapters
node_node_prisma -->|"implements"| node_node_schema
node_node_dev_keys_route -->|"uses"| node_node_encryption
node_node_connections_route -->|"stores data"| node_node_prisma
node_node_conversations_route -->|"stores data"| node_node_prisma
node_node_auth_route -->|"reads users"| node_node_prisma
node_node_schema -->|"defines"| node_node_auth_route

click node_node_app_root "https://github.com/alimomin-12/heliosprimer/blob/master/app/layout.tsx"
click node_node_public_home "https://github.com/alimomin-12/heliosprimer/blob/master/app/page.tsx"
click node_node_login "https://github.com/alimomin-12/heliosprimer/blob/master/app/login/page.tsx"
click node_node_dashboard_layout "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/layout.tsx"
click node_node_sidebar "https://github.com/alimomin-12/heliosprimer/blob/master/components/layout/Sidebar.tsx"
click node_node_theme "https://github.com/alimomin-12/heliosprimer/blob/master/components/theme/ThemeProvider.tsx"
click node_node_chat_page "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/chat/page.tsx"
click node_node_connect_page "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/connect/page.tsx"
click node_node_history_page "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/history/page.tsx"
click node_node_overview_page "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/dashboard/page.tsx"
click node_node_changelog_page "https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/orchestrator-changelog/page.tsx"
click node_node_auth_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/auth/[...nextauth]/route.ts"
click node_node_chat_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/chat/route.ts"
click node_node_connections_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/connections/route.ts"
click node_node_conversations_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/conversations/route.ts"
click node_node_orchestrate_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/orchestrate/route.ts"
click node_node_dev_keys_route "https://github.com/alimomin-12/heliosprimer/blob/master/app/api/dev/keys/route.ts"
click node_node_auth_lib "https://github.com/alimomin-12/heliosprimer/blob/master/lib/auth.ts"
click node_node_encryption "https://github.com/alimomin-12/heliosprimer/blob/master/lib/encryption.ts"
click node_node_prisma "https://github.com/alimomin-12/heliosprimer/blob/master/lib/prisma.ts"
click node_node_schema "https://github.com/alimomin-12/heliosprimer/blob/master/prisma/schema.prisma"
click node_node_orchestrator "https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/orchestrator.ts"
click node_node_registry "https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/registry.ts"
click node_node_adapters "https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/adapters/openai.ts"

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_node_app_root,node_node_public_home,node_node_login,node_node_dashboard_layout,node_node_sidebar,node_node_theme,node_node_chat_page,node_node_connect_page,node_node_history_page,node_node_overview_page,node_node_changelog_page toneBlue
class node_node_auth_route,node_node_chat_route,node_node_connections_route,node_node_conversations_route,node_node_orchestrate_route,node_node_dev_keys_route toneAmber
class node_node_orchestrator,node_node_registry,node_node_adapters toneMint
class node_node_auth_lib,node_node_encryption,node_node_prisma,node_node_schema toneRose
```

## Components

### UI surfaces

Public and authenticated pages plus shared client shell

- [App shell](https://github.com/alimomin-12/heliosprimer/blob/master/app/layout.tsx): next app · Top-level Next.js App Router entry and global layout · `app/layout.tsx`
- [Landing](https://github.com/alimomin-12/heliosprimer/blob/master/app/page.tsx): public page · Public entry point for the product · `app/page.tsx`
- [Login](https://github.com/alimomin-12/heliosprimer/blob/master/app/login/page.tsx): auth page · Public sign-in flow · `app/login/page.tsx`
- [Dashboard shell](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/layout.tsx): protected layout · Authenticated application frame for the dashboard area · `app/(dashboard)/layout.tsx`
- [Sidebar](https://github.com/alimomin-12/heliosprimer/blob/master/components/layout/Sidebar.tsx): nav component · Primary navigation for the protected experience · `components/layout/Sidebar.tsx`
- [Theme UI](https://github.com/alimomin-12/heliosprimer/blob/master/components/theme/ThemeProvider.tsx): ui support · Theme selection and client-side theme persistence · `components/theme/ThemeProvider.tsx`
- [Chat](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/chat/page.tsx): dashboard page · Conversation interface for direct model interaction · `app/(dashboard)/chat/page.tsx`
- [Connections](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/connect/page.tsx): dashboard page · Provider credential management interface · `app/(dashboard)/connect/page.tsx`
- [History](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/history/page.tsx): dashboard page · Conversation browsing and retrieval surface · `app/(dashboard)/history/page.tsx`
- [Dashboard](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/dashboard/page.tsx): dashboard page · Overview surface inside the protected area · `app/(dashboard)/dashboard/page.tsx`
- [Orchestrator log](https://github.com/alimomin-12/heliosprimer/blob/master/app/(dashboard)/orchestrator-changelog/page.tsx): dashboard page · Page for orchestration-related notes and changes · `app/(dashboard)/orchestrator-changelog/page.tsx`

### Server routes

Next.js route handlers for auth, chat, state, and orchestration

- [Auth API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/auth/[...nextauth]/route.ts): route handler · NextAuth server endpoint for authentication · `app/api/auth/[...nextauth]/route.ts`
- [Chat API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/chat/route.ts): route handler · Server endpoint for direct chat inference · `app/api/chat/route.ts`
- [Connections API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/connections/route.ts): route handler · CRUD endpoint for provider connection records · `app/api/connections/route.ts`
- [Conversations API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/conversations/route.ts): route handler · CRUD endpoint for persisted conversations and messages · `app/api/conversations/route.ts`
- [Orchestrate API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/orchestrate/route.ts): route handler · Server endpoint for multi-model orchestration runs · `app/api/orchestrate/route.ts`
- [Dev keys API](https://github.com/alimomin-12/heliosprimer/blob/master/app/api/dev/keys/route.ts): route handler · Development endpoint for managing test credentials · `app/api/dev/keys/route.ts`

### AI runtime

Provider abstraction and multi-model orchestration

- [Orchestrator](https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/orchestrator.ts): ai coordinator · Coordinates master/slave multi-model execution and synthesis · `lib/ai/orchestrator.ts`
- [Model registry](https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/registry.ts): provider registry · Normalizes provider selection and adapter lookup · `lib/ai/registry.ts`
- [Provider adapters](https://github.com/alimomin-12/heliosprimer/blob/master/lib/ai/adapters/openai.ts): ai adapters · OpenAI, Gemini, DeepSeek, and Qwen provider implementations · `lib/ai/adapters/openai.ts`

### Data layer

Auth, encryption, and Prisma-backed persistence

- [Auth config](https://github.com/alimomin-12/heliosprimer/blob/master/lib/auth.ts): nextauth config · NextAuth v5 configuration and session behavior · `lib/auth.ts`
- [Encryption](https://github.com/alimomin-12/heliosprimer/blob/master/lib/encryption.ts): secret handling · Encrypts provider keys before storage and decrypts at runtime · `lib/encryption.ts`
- [Prisma](https://github.com/alimomin-12/heliosprimer/blob/master/lib/prisma.ts): db client · Singleton Prisma client for database access · `lib/prisma.ts`
- [SQLite schema](https://github.com/alimomin-12/heliosprimer/blob/master/prisma/schema.prisma): data model · Prisma schema for users, auth, conversations, connections, and orchestration state · `prisma/schema.prisma`

## Connections

- App shell → Landing: serves · Root app includes the public landing entry
- App shell → Login: serves · Root app includes the login flow
- App shell → Dashboard shell: hosts · App Router hosts the protected dashboard segment
- Dashboard shell → Sidebar: contains · Protected shell renders primary navigation
- Dashboard shell → Theme UI: wraps · Dashboard experience is themed client-side
- Sidebar → Chat: navigates · Sidebar links to chat
- Sidebar → Connections: navigates · Sidebar links to provider management
- Sidebar → History: navigates · Sidebar links to conversation history
- Sidebar → Dashboard: navigates · Sidebar links to dashboard overview
- Sidebar → Orchestrator log: navigates · Sidebar links to orchestration notes
- Login → Auth API: authenticates · Login flow depends on server-side NextAuth
- Auth API → Auth config: configured by · Route handler uses shared auth configuration
- Chat → Chat API: sends messages · Chat UI submits prompts to the chat endpoint
- Chat API → Model registry: resolves provider · Direct chat selects the configured model adapter
- Chat API → Encryption: loads secrets · Provider credentials are decrypted only at runtime
- Chat API → Conversations API: persists state · Chat flow stores conversation progress
- Connections → Connections API: manages · Connection UI creates and updates provider credentials
- Connections API → Encryption: encrypts keys · API stores secret material encrypted
- Connections API → Prisma: writes data · Connection records are persisted through Prisma
- History → Conversations API: reads history · History surface fetches stored conversations
- Orchestrate API → Orchestrator: executes · Route invokes the multi-model coordinator
- Orchestrator → Model registry: delegates to · Orchestrator uses provider lookup and normalization
- Orchestrator → Encryption: loads secrets · Orchestrator decrypts keys only when needed
- Orchestrator → Conversations API: records steps · Intermediate orchestration messages are persisted
- Model registry → Provider adapters: selects · Registry maps providers to concrete adapters
- Prisma → SQLite schema: implements · Prisma client is backed by the SQLite schema
- Dev keys API → Encryption: uses · Development credential flow also protects secrets
- Connections API → Prisma: stores data · Connection API persists records through Prisma
- Conversations API → Prisma: stores data · Conversation API persists sessions and messages through Prisma
- Auth API → Prisma: reads users · Auth flow depends on persisted auth state
- SQLite schema → Auth API: defines · Schema includes auth-related entities
