# codehagen/outpulse architecture

> Architecture diagram of the GitHub repository codehagen/outpulse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codehagen/outpulse
- Repository: https://github.com/codehagen/outpulse

## Overview

##### Project Type and Purpose
- Outpulse is a full-stack, monorepo web platform for creating and managing AI-powered outbound calling agents.
- It consists of two primary applications:
- apps/www – a Next.js (App Router) frontend with built-in API routes and server actions.
- apps/api – a standalone Hono-based REST API service (SDK backend).

##### File Structure Analysis
- Top-level apps/ folder splits frontend (www) and backend (api).
- apps/www contains:
- src/app – Next.js pages & API routes (e.g., /api/calls, /api/auth)
- src/actions – server actions invoked by client components
- components, hooks, lib – UI, utilities, auth/client integrations
- prisma/schema.prisma – database schema
- apps/api is a minimal Hono service exposing REST endpoints, likely used by third-party SDKs.
- Shared tooling and config managed via pnpm workspaces and tooling/tailwind.

##### Key Architectural Insights from README
- Monorepo deployed on Vercel (apps/www), with build commands, environment variables, and prisma migrations.
- Uses Neon (serverless Postgres), Prisma ORM, Better Auth for authentication, Twilio for telephony, OpenAI/ElevenLabs for AI, Stripe for billing, Resend for email.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        Browser["Browser/Mobile"]:::frontend
        NextUI["Next.js Frontend"]:::frontend
        NextApp["Pages & Server Components"]:::frontend
        NextAPIRoutes["API Routes (Internal UX)"]:::frontend
        SrvActions["Server Actions"]:::frontend
        AuthRoute["Auth Route Handler"]:::frontend
        AuthClient["Auth Client Utils"]:::frontend
        CallsInitiate["Call Initiation Endpoint"]:::frontend
        CallsPreview["Call Prompt Preview"]:::frontend
        CallsStream["Call Stream Endpoint"]:::frontend
        CallsTwiml["Twilio Webhook"]:::frontend
        CallsTest["Test Call Endpoint"]:::frontend
        APIKeysGet["Get API Keys Action"]:::frontend
        APIKeysUpdate["Update API Keys Action"]:::frontend
        PrismaSchema["Prisma Schema"]:::db
        DBInit["Prisma Client Init"]:::db
    end

    subgraph "Backend Layer"
        HonoAPI["Hono REST API Service"]:::backend
        HonoUtils["Hono Utils & Middleware"]:::backend
    end

    subgraph "Data/Auth Layer"
        DB["Neon Postgres (Prisma)"]:::db
        Auth["Better Auth Service"]:::db
    end

    subgraph "External Services"
        OpenAI["OpenAI"]:::external
        Eleven["ElevenLabs"]:::external
        Twilio["Twilio"]:::external
        Stripe["Stripe"]:::external
        Resend["Resend"]:::external
    end

    %% Flows
    Browser <-->|"HTTP/WS"| NextUI
    NextUI -->|"Server Actions"| SrvActions
    NextUI -->|"API Calls"| NextAPIRoutes
    NextAPIRoutes -->|"Prisma Client"| DB
    SrvActions -->|"Prisma Client"| DB
    NextAPIRoutes -->|"Auth Check"| Auth
    SrvActions -->|"Auth Check"| Auth
    NextAPIRoutes -->|"HTTP"| OpenAI
    NextAPIRoutes -->|"HTTP"| Eleven
    NextAPIRoutes -->|"Twilio SDK"| Twilio
    NextAPIRoutes -->|"Webhook Setup"| Twilio
    NextAPIRoutes -->|"HTTP"| Stripe
    NextAPIRoutes -->|"SMTP API"| Resend
    HonoAPI -->|"Prisma Client"| DB
    HonoAPI -->|"Auth Middleware"| Auth
    Stripe -->|"Webhook"| NextAPIRoutes
    Twilio -->|"Webhook"| NextAPIRoutes

    %% Click Events - Frontend
    click NextUI "https://github.com/codehagen/outpulse/tree/main/apps/www"
    click NextApp "https://github.com/codehagen/outpulse/tree/main/apps/www/src/app"
    click NextAPIRoutes "https://github.com/codehagen/outpulse/tree/main/apps/www/src/app/api"
    click SrvActions "https://github.com/codehagen/outpulse/tree/main/apps/www/src/actions"
    click AuthRoute "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/auth/[...all]/route.ts"
    click AuthClient "https://github.com/codehagen/outpulse/blob/main/apps/www/src/lib/auth-client.ts"
    click CallsInitiate "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/calls/initiate/route.ts"
    click CallsPreview "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/calls/preview-prompt/route.ts"
    click CallsStream "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/calls/stream/route.ts"
    click CallsTwiml "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/calls/twiml/route.ts"
    click CallsTest "https://github.com/codehagen/outpulse/blob/main/apps/www/src/app/api/calls/test/route.ts"
    click APIKeysGet "https://github.com/codehagen/outpulse/blob/main/apps/www/src/actions/user/get-api-keys.ts"
    click APIKeysUpdate "https://github.com/codehagen/outpulse/blob/main/apps/www/src/actions/user/update-api-keys.ts"
    click PrismaSchema "https://github.com/codehagen/outpulse/blob/main/apps/www/prisma/schema.prisma"
    click DBInit "https://github.com/codehagen/outpulse/blob/main/apps/www/utils/db.ts"

    %% Click Events - Backend
    click HonoAPI "https://github.com/codehagen/outpulse/blob/main/apps/api/src/index.ts"
    click HonoUtils "https://github.com/codehagen/outpulse/blob/main/apps/api/src/utils.ts"

    %% Click Events - Config
    click EnvRoot "https://github.com/codehagen/outpulse/blob/main/.env.example"
    click EnvAPI "https://github.com/codehagen/outpulse/blob/main/apps/api/.env.example"
    click TailwindFE "https://github.com/codehagen/outpulse/blob/main/apps/www/tailwind.config.ts"
    click TailwindTool "https://github.com/codehagen/outpulse/blob/main/tooling/tailwind/tailwind.config.ts"
    click MonorepoWS "https://github.com/codehagen/outpulse/blob/main/pnpm-workspace.yaml"
    click MonorepoWS "https://github.com/codehagen/outpulse/blob/main/turbo.json"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#3399FF,color:#000;
    classDef backend fill:#D0FFD6,stroke:#28A745,color:#000;
    classDef db fill:#E5D6FF,stroke:#6F42C1,color:#000;
    classDef external fill:#F0F0F0,stroke:#6C757D,color:#000
```
