How alimomin-12/heliosprimer works
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: Sidebar.tsx Sidebar · prisma.ts Prisma · chat/route.ts Chat API · connections/route.ts Connections API
Components 24
UI surfaces
Public and authenticated pages plus shared client shell
- App shell · Top-level Next.js App Router entry and global layout
app/layout.tsx - Landing · Public entry point for the product
app/page.tsx - Login · Public sign-in flow
app/login/page.tsx - Dashboard shell · Authenticated application frame for the dashboard area
app/(dashboard)/layout.tsx - Sidebar · Primary navigation for the protected experience
components/layout/Sidebar.tsx - Theme UI · Theme selection and client-side theme persistence
components/theme/ThemeProvider.tsx - Chat · Conversation interface for direct model interaction
app/(dashboard)/chat/page.tsx - Connections · Provider credential management interface
app/(dashboard)/connect/page.tsx - History · Conversation browsing and retrieval surface
app/(dashboard)/history/page.tsx - Dashboard · Overview surface inside the protected area
app/(dashboard)/dashboard/page.tsx - Orchestrator log · 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 · NextAuth server endpoint for authentication
app/api/auth/[...nextauth]/route.ts - Chat API · Server endpoint for direct chat inference
app/api/chat/route.ts - Connections API · CRUD endpoint for provider connection records
app/api/connections/route.ts - Conversations API · CRUD endpoint for persisted conversations and messages
app/api/conversations/route.ts - Orchestrate API · Server endpoint for multi-model orchestration runs
app/api/orchestrate/route.ts - Dev keys API · Development endpoint for managing test credentials
app/api/dev/keys/route.ts
AI runtime
Provider abstraction and multi-model orchestration
- Orchestrator · Coordinates master/slave multi-model execution and synthesis
lib/ai/orchestrator.ts - Model registry · Normalizes provider selection and adapter lookup
lib/ai/registry.ts - Provider adapters · OpenAI, Gemini, DeepSeek, and Qwen provider implementations
lib/ai/adapters/openai.ts
Data layer
Auth, encryption, and Prisma-backed persistence
- Auth config · NextAuth v5 configuration and session behavior
lib/auth.ts - Encryption · Encrypts provider keys before storage and decrypts at runtime
lib/encryption.ts - Prisma · Singleton Prisma client for database access
lib/prisma.ts - SQLite schema · Prisma schema for users, auth, conversations, connections, and orchestration state
prisma/schema.prisma
Connections 31
- 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