# mananmodi1487/orvyn architecture

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

- Interactive diagram: https://gitdiagram.com/mananmodi1487/orvyn
- Repository: https://github.com/mananmodi1487/orvyn

## Overview

ORVYN’s supplied README describes a UI foundation with an intentionally unwired composer, but the source index and excerpts show a substantially expanded application: authenticated workspace, AI chat and usage accounting, conversation APIs backed by Supabase, and a local coding-agent CLI. The principal evidenced flow is a signed-in request to the chat route, which validates it, resolves a gateway, streams events, and records usage. Many UI, provider, auth, and CLI implementations were not sampled, so their internal connections are omitted rather than inferred.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/chat/route.ts) (Chat endpoint), [`src/app/page.tsx`](https://github.com/mananmodi1487/orvyn/blob/main/src/app/page.tsx) (Home entry), [`src/lib/ai/gateway.ts`](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/gateway.ts) (Model gateway), [`src/app/api/conversations/[id]/messages/route.ts`](https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/conversations/%5Bid%5D/messages/route.ts) (Message endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_home["Home entry<br/>[page.tsx]"]
  node_shell["Workspace shell"]
end

subgraph group_identity["Identity"]
  node_authpanel["Sign-in panel<br/>[auth-panel.tsx]"]
  node_authactions["Auth actions<br/>[actions.ts]"]
  node_session["Session lookup<br/>[session.ts]"]
  node_guard["Chat auth guard<br/>[guard.ts]"]
end

subgraph group_chat["AI chat"]
  node_chatroute["Chat endpoint<br/>[route.ts]"]
  node_request["Request validation<br/>[chat-request.ts]"]
  node_chatservice["Stream service<br/>[chat-service.ts]"]
  node_runtime["AI runtime<br/>[runtime.ts]"]
  node_gateway["Model gateway<br/>[gateway.ts]"]
  node_providers["Model providers"]
  node_usage["Usage accounting<br/>[usage-store.ts]"]
  node_usageapi["Usage endpoint<br/>[route.ts]"]
end

subgraph group_conversations["Conversation data"]
  node_convapi["Conversation endpoints"]
  node_messageapi["Message endpoints<br/>[route.ts]"]
  node_titles["Conversation titles"]
  node_supabase["Supabase data service<br/>[server.ts]"]
  node_database[("Supabase database")]
end

subgraph group_coding["Coding agent"]
  node_agentcli["Agent CLI<br/>[orvyn-agent.ts]"]
  node_agentserver["Agent server<br/>[agent.ts]"]
  node_planner["Task planner<br/>[planner.ts]"]
  node_agenttools["Agent tools<br/>[tools.ts]"]
  node_agentbridge["Browser bridge<br/>[bridge.ts]"]
end

node_visitor(("Workspace user"))

node_visitor -->|"opens workspace"| node_home
node_home -->|"reads session"| node_session
node_home -->|"renders signed-out"| node_authpanel
node_home -->|"renders signed-in"| node_shell
node_authpanel -->|"submits credentials"| node_authactions
node_visitor -.->|"posts chat"| node_chatroute
node_chatroute -->|"checks access"| node_guard
node_chatroute -->|"validates body"| node_request
node_chatroute -->|"gets gateway"| node_runtime
node_runtime -.->|"provides gateway"| node_gateway
node_chatroute -->|"ranks candidates"| node_gateway
node_chatroute -->|"streams events"| node_chatservice
node_chatservice -->|"streams selected"| node_gateway
node_gateway -.->|"dispatches generation"| node_providers
node_chatroute -->|"records usage"| node_usage
node_usageapi -->|"reads summary"| node_usage
node_convapi -->|"queries data"| node_supabase
node_messageapi -->|"reads and writes"| node_supabase
node_convapi -->|"persists conversations"| node_database
node_messageapi -->|"persists messages"| node_database
node_messageapi -->|"schedules title"| node_titles
node_agentcli -.->|"starts server"| node_agentserver
node_agentserver -.->|"uses planner"| node_planner
node_agentserver -.->|"uses tools"| node_agenttools
node_shell -.->|"connects agent"| node_agentbridge

click node_home "https://github.com/mananmodi1487/orvyn/blob/main/src/app/page.tsx"
click node_shell "https://github.com/mananmodi1487/orvyn/blob/main/src/components/workspace/workspace-shell.tsx"
click node_authpanel "https://github.com/mananmodi1487/orvyn/blob/main/src/components/workspace/auth-panel.tsx"
click node_authactions "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/actions.ts"
click node_session "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/session.ts"
click node_guard "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/guard.ts"
click node_chatroute "https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/chat/route.ts"
click node_request "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/chat-request.ts"
click node_chatservice "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/chat-service.ts"
click node_runtime "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/runtime.ts"
click node_gateway "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/gateway.ts"
click node_providers "https://github.com/mananmodi1487/orvyn/tree/main/src/lib/ai/providers"
click node_usage "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/usage-store.ts"
click node_usageapi "https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/usage/route.ts"
click node_convapi "https://github.com/mananmodi1487/orvyn/tree/main/src/app/api/conversations"
click node_messageapi "https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/conversations/%5Bid%5D/messages/route.ts"
click node_titles "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/conversation-titles.ts"
click node_supabase "https://github.com/mananmodi1487/orvyn/blob/main/src/utils/supabase/server.ts"
click node_agentcli "https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/bin/orvyn-agent.ts"
click node_agentserver "https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/agent.ts"
click node_planner "https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/planner.ts"
click node_agenttools "https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/tools.ts"
click node_agentbridge "https://github.com/mananmodi1487/orvyn/blob/main/src/lib/agent/bridge.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_home,node_shell,node_visitor toneBlue
class node_authpanel,node_authactions,node_session,node_guard toneAmber
class node_chatroute,node_request,node_chatservice,node_runtime,node_gateway,node_providers,node_usage,node_usageapi toneMint
class node_convapi,node_messageapi,node_titles,node_supabase,node_database toneRose
class node_agentcli,node_agentserver,node_planner,node_agenttools,node_agentbridge toneIndigo
```

## Components

### Workspace UI

- [Home entry](https://github.com/mananmodi1487/orvyn/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Workspace shell](https://github.com/mananmodi1487/orvyn/blob/main/src/components/workspace/workspace-shell.tsx): `src/components/workspace/workspace-shell.tsx`

### Identity

- [Sign-in panel](https://github.com/mananmodi1487/orvyn/blob/main/src/components/workspace/auth-panel.tsx): `src/components/workspace/auth-panel.tsx`
- [Auth actions](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/actions.ts): `src/lib/auth/actions.ts`
- [Session lookup](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/session.ts): `src/lib/auth/session.ts`
- [Chat auth guard](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/auth/guard.ts): `src/lib/auth/guard.ts`

### AI chat

- [Chat endpoint](https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Request validation](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/chat-request.ts): `src/lib/ai/chat-request.ts`
- [Stream service](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/chat-service.ts): `src/lib/ai/chat-service.ts`
- [AI runtime](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/runtime.ts): `src/lib/ai/runtime.ts`
- [Model gateway](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/gateway.ts): `src/lib/ai/gateway.ts`
- [Model providers](https://github.com/mananmodi1487/orvyn/tree/main/src/lib/ai/providers): `src/lib/ai/providers`
- [Usage accounting](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/usage-store.ts): `src/lib/ai/usage-store.ts`
- [Usage endpoint](https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/usage/route.ts): `src/app/api/usage/route.ts`

### Conversation data

- [Conversation endpoints](https://github.com/mananmodi1487/orvyn/tree/main/src/app/api/conversations): `src/app/api/conversations`
- [Message endpoints](https://github.com/mananmodi1487/orvyn/blob/main/src/app/api/conversations/%5Bid%5D/messages/route.ts): `src/app/api/conversations/[id]/messages/route.ts`
- [Conversation titles](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/ai/conversation-titles.ts): `src/lib/ai/conversation-titles.ts`
- [Supabase data service](https://github.com/mananmodi1487/orvyn/blob/main/src/utils/supabase/server.ts): `src/utils/supabase/server.ts`
- **Supabase database**

### Coding agent

- [Agent CLI](https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/bin/orvyn-agent.ts): `packages/agent-cli/bin/orvyn-agent.ts`
- [Agent server](https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/agent.ts): `packages/agent-cli/src/server/agent.ts`
- [Task planner](https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/planner.ts): `packages/agent-cli/src/server/planner.ts`
- [Agent tools](https://github.com/mananmodi1487/orvyn/blob/main/packages/agent-cli/src/server/tools.ts): `packages/agent-cli/src/server/tools.ts`
- [Browser bridge](https://github.com/mananmodi1487/orvyn/blob/main/src/lib/agent/bridge.ts): `src/lib/agent/bridge.ts`

### Other components

- **Workspace user**

## Connections

- Workspace user → Home entry: opens workspace (evidence: `src/app/page.tsx`)
- Home entry → Session lookup: reads session (evidence: `src/app/page.tsx`)
- Home entry → Sign-in panel: renders signed-out (evidence: `src/app/page.tsx`)
- Home entry → Workspace shell: renders signed-in (evidence: `src/app/page.tsx`)
- Sign-in panel → Auth actions: submits credentials (evidence: `src/components/workspace/auth-panel.tsx`)
- Workspace user → Chat endpoint: posts chat
- Chat endpoint → Chat auth guard: checks access (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Request validation: validates body (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → AI runtime: gets gateway (evidence: `src/app/api/chat/route.ts`)
- AI runtime → Model gateway: provides gateway
- Chat endpoint → Model gateway: ranks candidates (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Stream service: streams events (evidence: `src/app/api/chat/route.ts`)
- Stream service → Model gateway: streams selected (evidence: `src/lib/ai/chat-service.ts`)
- Model gateway → Model providers: dispatches generation
- Chat endpoint → Usage accounting: records usage (evidence: `src/app/api/chat/route.ts`)
- Usage endpoint → Usage accounting: reads summary (evidence: `src/app/api/usage/route.ts`)
- Conversation endpoints → Supabase data service: queries data (evidence: `src/app/api/conversations/route.ts`)
- Message endpoints → Supabase data service: reads and writes (evidence: `src/app/api/conversations/[id]/messages/route.ts`)
- Conversation endpoints → Supabase database: persists conversations (evidence: `src/app/api/conversations/route.ts`)
- Message endpoints → Supabase database: persists messages (evidence: `src/app/api/conversations/[id]/messages/route.ts`)
- Message endpoints → Conversation titles: schedules title (evidence: `src/app/api/conversations/[id]/messages/route.ts`)
- Agent CLI → Agent server: starts server
- Agent server → Task planner: uses planner
- Agent server → Agent tools: uses tools
- Workspace shell → Browser bridge: connects agent
