Nexus Orchestrator · Docs Architecture Roadmap Changelog GitHub ↗

Nexus Orchestrator

Architecture Overview · Express + React · v1.2.0 · Port 3000

Frontend — React 19 + Vite 6 + Tailwind 4
useAuth
login · logout · register · httpOnly cookie
useConnection
provider health · model discovery
useConfig
config CRUD · categories · per-user
useConversations
create · select · rename · delete · projects
useChat
send · route intent · SSE stream · web search
usePersistentToggle
localStorage-backed collapse state
usePersistentTab
active tab persists across refresh
Sidebar
  • Paginated conversation list
  • Double-click rename
  • Right-click context menu
  • Project folders
  • Collapse / expand projects
Chat Tab
  • ChatMessage (MD + KaTeX)
  • Code blocks + copy button
  • Thinking block (collapsible)
  • RoutingStatus (live steps)
  • RoutingAnalysis (expand)
  • Web search sources
  • ChatInput + attachments
  • Globe toggle (web search)
  • Brain toggle (thinking)
Models Tab
  • ProviderConfig (collapsible)
  • RouterConfig (collapsible)
  • CategoryMappings (collapsible)
  • DiscoveredModels (collapsible)
  • Multi-provider support
  • Provider-grouped model list
System Tab
  • User management (admin)
  • Toggle registration
  • Export config JSON
  • Export conversations JSON
  • Router cache toggle
  • Show thinking toggle (global)
  • Version display
▼ HTTP / SSE · same-origin · httpOnly session cookie ▼
Backend — Express 4 · TypeScript 5.8 · Node 20 · Pino Logging
Auth
POST/api/auth/loginset session cookie
POST/api/auth/logoutclear cookie
GET/api/auth/statusisAuthenticated + user
POST/api/auth/registerself-registration
PUT/api/auth/passwordchange own password 🔒
Admin
GET/api/admin/userslist users ⚙
POST/api/admin/userscreate user ⚙
DEL/api/admin/users/:iddelete user ⚙
PUT/api/admin/users/:id/resetreset password ⚙
GET/api/admin/settingsregistration toggle ⚙
PUT/api/admin/settingsupdate settings ⚙
Config · Models · Router · Chat
GET/api/configmasked config 🔒
POST/api/configsave + validate URLs 🔒
GET/api/healthping all providers 🔒
GET/api/modelsdiscover models 🔒
POST/api/routerclassify intent 🔒
POST/api/chatSSE stream 🔒
Conversations · Projects
GET/api/conversationspaginated list 🔒
GET/api/conversations/exportfull export 🔒
GET/api/conversations/:idfull messages 🔒
POST/api/conversationscreate 🔒
PUT/api/conversations/:idupdate 🔒
DEL/api/conversations/:iddelete 🔒
PATCH/api/conversations/:id/projectassign project 🔒
GET/api/projectslist projects 🔒
POST/api/projectscreate project 🔒
PUT/api/projects/:idrename / collapse 🔒
DEL/api/projects/:iddelete project 🔒
GET*serve Vite SPA
httpOnly Session Cookie Timing-Safe API Key Compare bcrypt Password Hash AES-256-GCM Encryption Same-Origin CORS Security Headers (CSP · HSTS · X-Frame) trust proxy · req.secure cookie npm · RFC-compliant parsing SSRF — Metadata Endpoint Block URL Scheme Validation Auth Rate Limiter (20/15 min) Body Limits (1 MB global · 20 MB chat) Session Sweep (hourly) Session Cap (10 per user) Password Complexity (upper+lower+digit) Admin Settings — Strict Zod Schema
▼ Message Flow ▼
Request Flow — User Message → Streamed Response
1
Attachment Check
  • Images → force VISION
  • Docs → force DOCUMENT
  • None → router decides
→
2
Intent Router
  • POST /api/router
  • ROUTER_MODEL classifies
  • 8 categories
  • Cache hit → skip LLM call
  • Blank URL → local fallback
→
3
Web Search (optional)
  • Tool call injected if enabled
  • SearXNG queried server-side
  • Results appended to context
  • FAST category skips search
→
4
Provider Dispatch
  • Ollama detected via /api/tags first
  • Ollama → /api/chat + think:true
  • Others → /v1/chat/completions
  • 5 retries · 30s backoff
  • Fallback model chain
  • think:true retry on 400
→
5
SSE Stream
  • Chunk-by-chunk response
  • Thinking block streamed live
  • Markdown + KaTeX render
  • Code blocks + copy button
  • Usage tokens tracked
  • Routing analysis shown
  • Web search sources shown
→
6
Persist
  • PUT /api/conversations/:id
  • Messages + routing saved
  • SQLite · AES-256-GCM
  • Auto-title from prompt
Storage — SQLite (better-sqlite3) · AES-256-GCM · /app/data/
users
  • id · username · role
  • password_hash (bcrypt)
  • created_at
user_config
  • localProviders [{name,url,key}]
  • cloudUrl · cloudKey
  • router {model,url,key}
  • categories {models[],provider}
  • searxng {url,alwaysOn}
  • showThinking (boolean)
  • Encrypted at rest
conversations
  • id · title · user_id
  • messages[] with roles
  • routing decisions
  • timestamps · usage
  • web search sources
projects
  • id · name · user_id
  • collapsed state
  • conversations assigned by ID
admin_settings
  • registrationEnabled
External Providers — OpenAI-Compatible
Local Providers (multiple)
http://[LAN-IP]:[port]
  • Ollama
  • llama-swap
  • llama.cpp
  • LM Studio
  • Open WebUI
  • Any OpenAI-compat endpoint
Cloud Provider
https://[provider]/v1
  • Gemini (googleapis)
  • OpenRouter
  • OpenAI
  • Any OpenAI-compat API
Intent Router
ROUTER_URL (or local fallback)
  • Classifies into 8 categories
  • CODING · REASONING · CREATIVE
  • VISION · DOCUMENT · SECURITY
  • GENERAL · FAST
  • Returns category + model + confidence
  • 5-min LRU cache (optional)