# cache-me/ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/cache-me/ai-agent
- Repository: https://github.com/cache-me/ai-agent

## Overview

##### Project type and purpose
- This is a full‑stack web application starter built on Next.js (App Router), TypeScript, Shadcn UI + Tailwind, Prisma ORM, tRPC, and NextAuth for authentication.
- It also includes AI “agent” modules (chat, job, portfolio) under `src/server/ai` and supports email/SMS via `src/lib`.

##### File structure
- Top‑level config: `.eslintrc.js`, `tsconfig.json`, `docker/`, `prisma/schema.prisma`, `next.config.js`, `package.json`.
- `src/app`: Next.js App Router layout, UI for authenticated vs. public, API route entrypoints (`/api/auth/[...nextauth]`, `/api/trpc/[trpc]`).
- `src/client/trpc`: tRPC client & React Query integration.
- `src/components/ui`: shared UI primitives.
- `src/lib`: low‑level helpers (env, auth, email, sms, validation).
- `src/server/api`: tRPC server context & routers (user router).
- `src/server/ai`: AI “agent” services.
- `src/server/db.ts` & `prisma/schema.prisma`: database layer (PostgreSQL).
- `docker/`: containers for `web` (Next.js) and `db` (Postgres) via Docker Compose.

##### README
- Confirms use of Bun, Next.js, Prisma, tRPC, Tailwind, Shadcn UI, NextAuth.

##### Key pointers
- App Router’s public vs. authenticated layout branching.
- Single source of truth for API contracts via tRPC.
- Environment variables feeding into Docker and server config.
- Don’t over‑partition—focus on the main logical components and their integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)"
        direction TB
        Browser["Browser"]:::external
        subgraph "Presentation (UI)"
            direction TB
            PublicLayout["Public Layout"]:::frontend
            AuthShell["Authenticated App Shell"]:::frontend
            TRPCClient["tRPC Client"]:::frontend
        end
    end

    %% Server Side within Docker
    subgraph "Docker Network"
        direction TB
        subgraph "Web Server"
            direction TB
            NextApp["Next.js App Server"]:::backend
            NextAuthAPI["NextAuth API Route"]:::backend
            TRPCApi["tRPC API Route"]:::backend
            EnvLib["Env & Helpers"]:::backend
            Storage["File Storage Abstraction"]:::backend
        end
        DB["PostgreSQL"]:::datastore
        subgraph "AI Agents"
            direction TB
            ChatAgent["Chat Agent"]:::backend
            JobAgent["Job Agent"]:::backend
            PortfolioAgent["Portfolio Manager"]:::backend
        end
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    EmailService["Email Provider"]:::external
    SMSService["SMS Gateway"]:::external

    %% Connections
    Browser -->|HTTP/HTTPS| PublicLayout
    Browser -->|HTTP/HTTPS| AuthShell
    PublicLayout -->|SSR/SSG| NextApp
    AuthShell -->|SSR/SSG| NextApp
    AuthShell --> TRPCClient
    PublicLayout --> TRPCClient
    TRPCClient -->|RPC calls| TRPCApi
    NextApp -->|handles Auth| NextAuthAPI
    TRPCApi -->|uses context| EnvLib
    TRPCApi -->|CRUD ops| PrismaLayer["Prisma ORM"]:::backend
    PrismaLayer -->|SQL queries| DB
    NextAuthAPI -->|session/user| DB
    TRPCApi -->|invoke| ChatAgent
    TRPCApi -->|invoke| JobAgent
    TRPCApi -->|invoke| PortfolioAgent
    ChatAgent -->|calls| OpenAI
    JobAgent -->|calls| OpenAI
    PortfolioAgent -->|calls| OpenAI
    TRPCApi -->|sends email| EmailService
    TRPCApi -->|sends SMS| SMSService

    %% Click Events
    click PublicLayout "https://github.com/cache-me/ai-agent/blob/master/src/app/layout.tsx"
    click AuthShell "https://github.com/cache-me/ai-agent/blob/master/src/app/(authenticated-app)/_components/app-shell.tsx"
    click NextAuthAPI "https://github.com/cache-me/ai-agent/blob/master/src/app/api/auth/[...nextauth]/route.ts"
    click TRPCApi "https://github.com/cache-me/ai-agent/blob/master/src/app/api/trpc/[trpc]/route.ts"
    click TRPCClient "https://github.com/cache-me/ai-agent/blob/master/src/client/trpc/client.ts"
    click EnvLib "https://github.com/cache-me/ai-agent/blob/master/src/lib/env.ts"
    click Storage "https://github.com/cache-me/ai-agent/blob/master/src/server/storage.ts"
    click ChatAgent "https://github.com/cache-me/ai-agent/blob/master/src/server/ai/agents/chat-agent.ts"
    click JobAgent "https://github.com/cache-me/ai-agent/blob/master/src/server/ai/agents/job-agent.ts"
    click PortfolioAgent "https://github.com/cache-me/ai-agent/blob/master/src/server/ai/agents/portfolio-manager.ts"
    click PrismaLayer "https://github.com/cache-me/ai-agent/blob/master/prisma/schema.prisma"
    click NextApp "https://github.com/cache-me/ai-agent/blob/master/src/app/layout.tsx"
    click DB "https://github.com/cache-me/ai-agent/blob/master/docker/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#000
    classDef backend fill:#D4F8C4,stroke:#000
    classDef datastore fill:#FFE4B5,stroke:#000
    classDef external fill:#E0E0E0,stroke:#000
```
