# techstack-ujjwal/dolphin architecture

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

- Interactive diagram: https://gitdiagram.com/techstack-ujjwal/dolphin
- Repository: https://github.com/techstack-ujjwal/dolphin

## Overview

DOLPHIN is an AI-powered CLI with chat, tool-calling, and application-generation modes, plus a web-assisted device-authentication flow. The CLI workflow authenticates the user, offers a mode, then persists conversations and exchanges messages with the AI; agent mode additionally generates files in the working directory. The tree and excerpts also show a Next.js sign-in/device-approval client. Some client-to-server wiring and the internals of tool and application generation were not sampled, so those connections are not inferred.

Main entry points: [`server/src/cli/commander/auth/ai/wakeup.js`](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/commander/auth/ai/wakeup.js) (Mode selection), [`server/src/cli/chat/chat-with-ai-tool.js`](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-ai-tool.js) (Tool calling), [`server/src/cli/ai/openai-service.js`](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/ai/openai-service.js) (AI service), [`server/src/cli/main.js`](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/main.js) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_main["CLI commands<br/>[main.js]"]
  node_login["Login commands<br/>[login.js]"]
  node_wakeup["Mode selection<br/>[wakeup.js]"]
end

subgraph group_ai["AI modes"]
  node_chat["Chat mode<br/>[chat-with-ai.js]"]
  node_toolchat["Tool calling"]
  node_agentchat["Agent mode"]
  node_openai["AI service<br/>[openai-service.js]"]
  node_gptconfig["Model config<br/>[gpt.config.js]"]
  node_toolconfig["Tool config<br/>[tool.config.js]"]
  node_agentconfig["Generation config<br/>[agent.config.js]"]
  node_toolservices["Search, execution, URL context"]
  node_generatedfiles["Generated application files"]
end

subgraph group_state["Identity and conversation state"]
  node_chatservice["Conversation service<br/>[chat.service.js]"]
  node_database[("PostgreSQL data<br/>[db.js]")]
  node_authservice["Auth service<br/>[auth.js]"]
end

subgraph group_web["Web authentication"]
  node_webpages["Sign-in and device pages<br/>[page.tsx]"]
  node_loginform["Login form<br/>[login-form.tsx]"]
  node_authclient["Browser auth client<br/>[auth-client.ts]"]
  node_devicepage["Device approval<br/>[page.tsx]"]
  node_approvepage["Approval page<br/>[page.tsx]"]
end

node_user(("CLI user"))
node_github(("GitHub"))
node_openaiservice(("OpenAI"))

node_user -->|"runs commands"| node_main
node_main -->|"registers auth"| node_login
node_main -->|"registers mode command"| node_wakeup
node_main -->|"loads direct chat"| node_chat
node_wakeup -->|"reads token"| node_login
node_wakeup -->|"looks up user"| node_database
node_wakeup -->|"dispatches chat"| node_chat
node_wakeup -->|"dispatches tools"| node_toolchat
node_wakeup -->|"dispatches agent"| node_agentchat
node_chat -->|"loads and saves messages"| node_chatservice
node_toolchat -->|"loads and saves messages"| node_chatservice
node_agentchat -->|"loads and saves messages"| node_chatservice
node_chatservice -->|"reads and writes"| node_database
node_chat -->|"requests responses"| node_openai
node_toolchat -->|"requests tool responses"| node_openai
node_agentchat -->|"requests generation"| node_openai
node_openai -->|"reads model settings"| node_gptconfig
node_openai -.->|"calls model API"| node_openaiservice
node_toolchat -->|"gets available tools"| node_toolconfig
node_toolchat -.->|"offers tool capabilities"| node_toolservices
node_agentchat -->|"generates application"| node_agentconfig
node_agentconfig -.->|"writes project files"| node_generatedfiles
node_authservice -->|"uses Prisma adapter"| node_database
node_login -.->|"polls device authorization"| node_authservice
node_loginform -->|"starts GitHub sign-in"| node_authclient
node_authservice -->|"configures OAuth provider"| node_github

click node_main "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/main.js"
click node_login "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/commander/auth/auth/login.js"
click node_wakeup "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/commander/auth/ai/wakeup.js"
click node_chat "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-ai.js"
click node_toolchat "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-ai-tool.js"
click node_agentchat "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-aiagent.js"
click node_openai "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/ai/openai-service.js"
click node_gptconfig "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/gpt.config.js"
click node_toolconfig "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/tool.config.js"
click node_agentconfig "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/agent.config.js"
click node_chatservice "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/service/chat.service.js"
click node_database "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/lib/db.js"
click node_authservice "https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/lib/auth.js"
click node_webpages "https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/auth/sign-in/page.tsx"
click node_loginform "https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/components/login-form.tsx"
click node_authclient "https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/lib/auth-client.ts"
click node_devicepage "https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/device/page.tsx"
click node_approvepage "https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/approve/page.tsx"

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_main,node_login,node_wakeup,node_user toneBlue
class node_chat,node_toolchat,node_agentchat,node_openai,node_gptconfig,node_toolconfig,node_agentconfig,node_toolservices,node_generatedfiles toneAmber
class node_chatservice,node_database,node_authservice toneMint
class node_webpages,node_loginform,node_authclient,node_devicepage,node_approvepage toneRose
class node_github,node_openaiservice toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/main.js): `server/src/cli/main.js`
- [Login commands](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/commander/auth/auth/login.js): `server/src/cli/commander/auth/auth/login.js`
- [Mode selection](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/commander/auth/ai/wakeup.js): `server/src/cli/commander/auth/ai/wakeup.js`

### AI modes

- [Chat mode](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-ai.js): `server/src/cli/chat/chat-with-ai.js`
- [Tool calling](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-ai-tool.js): `server/src/cli/chat/chat-with-ai-tool.js`
- [Agent mode](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/chat/chat-with-aiagent.js): `server/src/cli/chat/chat-with-aiagent.js`
- [AI service](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/cli/ai/openai-service.js): `server/src/cli/ai/openai-service.js`
- [Model config](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/gpt.config.js): `server/src/config/gpt.config.js`
- [Tool config](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/tool.config.js): `server/src/config/tool.config.js`
- [Generation config](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/config/agent.config.js): `server/src/config/agent.config.js`
- **Search, execution, URL context**
- **Generated application files**

### Identity and conversation state

- [Conversation service](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/service/chat.service.js): `server/src/service/chat.service.js`
- [PostgreSQL data](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/lib/db.js): `server/src/lib/db.js`
- [Auth service](https://github.com/techstack-ujjwal/dolphin/blob/main/server/src/lib/auth.js): `server/src/lib/auth.js`

### Web authentication

- [Sign-in and device pages](https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/auth/sign-in/page.tsx): `client/my-app/app/auth/sign-in/page.tsx`
- [Login form](https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/components/login-form.tsx): `client/my-app/components/login-form.tsx`
- [Browser auth client](https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/lib/auth-client.ts): `client/my-app/lib/auth-client.ts`
- [Device approval](https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/device/page.tsx): `client/my-app/app/device/page.tsx`
- [Approval page](https://github.com/techstack-ujjwal/dolphin/blob/main/client/my-app/app/approve/page.tsx): `client/my-app/app/approve/page.tsx`

### Other components

- **CLI user**
- **GitHub**
- **OpenAI**

## Connections

- CLI user → CLI commands: runs commands (evidence: `server/src/cli/main.js`)
- CLI commands → Login commands: registers auth (evidence: `server/src/cli/main.js`)
- CLI commands → Mode selection: registers mode command (evidence: `server/src/cli/main.js`)
- CLI commands → Chat mode: loads direct chat (evidence: `server/src/cli/main.js`)
- Mode selection → Login commands: reads token (evidence: `server/src/cli/commander/auth/ai/wakeup.js`)
- Mode selection → PostgreSQL data: looks up user (evidence: `server/src/cli/commander/auth/ai/wakeup.js`)
- Mode selection → Chat mode: dispatches chat (evidence: `server/src/cli/commander/auth/ai/wakeup.js`)
- Mode selection → Tool calling: dispatches tools (evidence: `server/src/cli/commander/auth/ai/wakeup.js`)
- Mode selection → Agent mode: dispatches agent (evidence: `server/src/cli/commander/auth/ai/wakeup.js`)
- Chat mode → Conversation service: loads and saves messages (evidence: `server/src/cli/chat/chat-with-ai.js`)
- Tool calling → Conversation service: loads and saves messages (evidence: `server/src/cli/chat/chat-with-ai-tool.js`)
- Agent mode → Conversation service: loads and saves messages (evidence: `server/src/cli/chat/chat-with-aiagent.js`)
- Conversation service → PostgreSQL data: reads and writes (evidence: `server/src/service/chat.service.js`)
- Chat mode → AI service: requests responses (evidence: `server/src/cli/chat/chat-with-ai.js`)
- Tool calling → AI service: requests tool responses (evidence: `server/src/cli/chat/chat-with-ai-tool.js`)
- Agent mode → AI service: requests generation (evidence: `server/src/cli/chat/chat-with-aiagent.js`)
- AI service → Model config: reads model settings (evidence: `server/src/cli/ai/openai-service.js`)
- AI service → OpenAI: calls model API
- Tool calling → Tool config: gets available tools (evidence: `server/src/cli/chat/chat-with-ai-tool.js`)
- Tool calling → Search, execution, URL context: offers tool capabilities (evidence: `README.md`)
- Agent mode → Generation config: generates application (evidence: `server/src/cli/chat/chat-with-aiagent.js`)
- Generation config → Generated application files: writes project files (evidence: `README.md`)
- Auth service → PostgreSQL data: uses Prisma adapter (evidence: `server/src/lib/auth.js`)
- Login commands → Auth service: polls device authorization (evidence: `server/src/cli/commander/auth/auth/login.js`)
- Login form → Browser auth client: starts GitHub sign-in (evidence: `client/my-app/components/login-form.tsx`)
- Auth service → GitHub: configures OAuth provider (evidence: `server/src/lib/auth.js`)
