# akshat-owo/down architecture

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

- Interactive diagram: https://gitdiagram.com/akshat-owo/down
- Repository: https://github.com/akshat-owo/down

## Overview

##### Project Type and Purpose
- “Down” is a full-stack web application (Next.js) that lets users upload PDFs, index them in a vector store, and chat with a bot that answers questions about the PDF content.
- It’s backed by a MySQL (PlanetScale) database (via Prisma), a Pinecone vector store, the OpenAI API for embeddings and chat, and Stripe for billing. Authentication uses Kinde.

##### File Structure
- src/app: Next.js 13 “app directory” with pages (/, /pricing, /dashboard, /auth-callback, etc.).
- src/app/api: Next.js API routes split into:
- auth/[kindeAuth] for login callbacks
- message and trpc endpoints for your chat backend
- uploadthing endpoints for PDF upload
- webhooks/stripe for billing events
- src/app/_trpc: client instantiation
- src/components: React UI, chat widgets, upload buttons, billing form, Navbars, etc.
- prisma/schema.prisma: DB schema
- src/lib: wrappers around OpenAI, Pinecone, Stripe, file-upload logic
- src/trpc: server-side TRPC init
- src/db/index.ts: Prisma client
- config files: stripe, infinite-query (TanStack Query), tailwind, next.config.js, etc.

##### README for Additional Insights
- Confirms tech stack (Next.js, Tailwind, Radix UI, PlanetScale, OpenAI, Pinecone).
- Explains user flows: signup/login, upload PDF, chat interface, billing.

a. Main Components
- Client Browser (React/Next.js)
- Next.js Server (app router + API routes + TRPC)
- Auth Service (Kinde)
- PDF-Upload Service (UploadThing)
- Chat Backend (TRPC handlers calling lib/openai & lib/pinecone)
- Database (PlanetScale via Prisma)
- Vector Store (Pinecone)
- LLM Service (OpenAI)
- Billing Service (Stripe + webhooks)

b. Relationships & Interactions
1. User Browser → Next.js pages for UI
2. Browser → API routes (via TRPC client or REST endpoints) for:
– Authentication → Kinde
– PDF upload → UploadThing → Next.js → store file metadata in PlanetScale
– Chat requests → TRPC endpoint → query Pinecone for relevant embeddings → call OpenAI → return answers
– Billing → Stripe Checkout → Webhook → Next.js /webhooks/stripe → update subscription in DB
3. Next.js Server ↔ PlanetScale (Prisma client) for user, file, billing records
4. Next.js Server ↔ Pinecone for vector insert/query
5. Next.js Server ↔ OpenAI (embeddings + chat completions)

c. Architectural Patterns & Principles
- Monolithic full-stack app using Next.js app router
- API boundary via Next.js API routes + TRPC for type-safe RPC
- Separation of concerns: UI, API, DB, vector store, billing, auth, external AI
- Dependency inversion: wrap external services in src/lib for easier testing/mocking

d. Key Technologies/Frameworks
- Next.js 13 (app router + server components)
- TRPC (end-to-end typesafe APIs)
- Prisma + PlanetScale (MySQL)
- Pinecone (vector search)
- OpenAI (GPT embeddings & chat)
- UploadThing (file hosting)
- Stripe (billing + webhooks)
- Kinde (authentication)
- Tailwind CSS & Radix UI for design

##### Detail without Over-Engineering
- How TRPC client.ts plugs into the TRPC routes on the server.
- Middleware.ts if applicable for cross-cutting concerns (authentication checks, logging).
- Don’t forget the Prisma schema leading to PlanetScale and the Pinecone indexer service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        direction TB
        ClientUI["Client Browser (Next.js UI)"]:::frontend
        TRPCClient["TRPC Client"]:::backend
    end

    subgraph "Backend Layer"
        direction TB
        NextServer["Next.js Server<br/>(App Router & API Routes)"]:::backend
        Middleware["Middleware"]:::middleware
        subgraph "API Routes"
            direction TB
            AuthAPI["Auth API (Kinde)"]:::backend
            UploadAPI["UploadThing API"]:::backend
            MessageAPI["Message API"]:::backend
            TRPCAPI["TRPC API"]:::backend
            WebhookAPI["Stripe Webhook API"]:::backend
        end
        subgraph "TRPC Setup"
            direction TB
            TRPCServerInit["TRPC Server Init"]:::backend
            TRPCRouterDef["TRPC Route Definitions"]:::backend
        end
    end

    subgraph "Libraries & Services"
        direction TB
        OpenAILib["OpenAI Service"]:::lib
        PineconeLib["Pinecone Service"]:::lib
        UploadThingLib["UploadThing Lib"]:::lib
        StripeWrapper["Stripe Wrapper"]:::lib
        Utils["Utilities"]:::lib
        Validator["Message Validator"]:::lib
    end

    subgraph "Data Stores"
        direction TB
        PrismaClient["Prisma Client"]:::datastore
        PrismaSchema["Prisma Schema"]:::datastore
        Pinecone["Pinecone Vector Store"]:::datastore
    end

    subgraph "Global Configuration"
        direction TB
        NextConfig["next.config.js"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        PostcssConfig["postcss.config.js"]:::config
        GlobalCSS["globals.css"]:::config
    end

    subgraph "External Services"
        direction TB
        Kinde["Kinde Auth"]:::external
        UploadThingExt["UploadThing"]:::external
        OpenAIExt["OpenAI API"]:::external
        PineconeExt["Pinecone API"]:::external
        StripeExt["Stripe API"]:::external
    end

    %% Connections
    ClientUI --> NextServer
    ClientUI --> TRPCClient
    ClientUI --> AuthAPI
    ClientUI --> UploadAPI
    ClientUI --> MessageAPI

    TRPCClient --> TRPCAPI
    TRPCAPI --> TRPCServerInit
    TRPCServerInit --> TRPCRouterDef

    NextServer -->|uses| Middleware
    NextServer -->|handles| AuthAPI
    NextServer -->|handles| UploadAPI
    NextServer -->|handles| MessageAPI
    NextServer -->|handles| TRPCAPI
    NextServer -->|handles| WebhookAPI

    NextServer --> PrismaClient
    PrismaClient --> PrismaSchema

    NextServer --> OpenAILib
    OpenAILib --> OpenAIExt

    NextServer --> PineconeLib
    PineconeLib --> PineconeExt
    PineconeLib --> Pinecone

    NextServer --> UploadThingLib
    UploadThingLib --> UploadThingExt

    NextServer --> StripeWrapper
    StripeWrapper --> StripeExt

    MessageAPI --> OpenAILib
    MessageAPI --> PineconeLib

    WebhookAPI --> StripeWrapper
    WebhookAPI --> PrismaClient

    %% Click Events
    click ClientUI "https://github.com/akshat-owo/down/tree/main/src/app"
    click TRPCClient "https://github.com/akshat-owo/down/blob/main/src/app/_trpc/client.ts"
    click AuthAPI "https://github.com/akshat-owo/down/blob/main/src/app/api/auth/[kindeAuth]/route.ts"
    click UploadAPI "https://github.com/akshat-owo/down/blob/main/src/app/api/uploadthing/route.ts"
    click UploadThingLib "https://github.com/akshat-owo/down/blob/main/src/lib/uploadthing.ts"
    click MessageAPI "https://github.com/akshat-owo/down/blob/main/src/app/api/message/route.ts"
    click TRPCAPI "https://github.com/akshat-owo/down/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click TRPCServerInit "https://github.com/akshat-owo/down/blob/main/src/trpc/index.ts"
    click TRPCRouterDef "https://github.com/akshat-owo/down/blob/main/src/trpc/trpc.ts"
    click OpenAILib "https://github.com/akshat-owo/down/blob/main/src/lib/openai.ts"
    click PineconeLib "https://github.com/akshat-owo/down/blob/main/src/lib/pinecone.ts"
    click PrismaSchema "https://github.com/akshat-owo/down/blob/main/prisma/schema.prisma"
    click PrismaClient "https://github.com/akshat-owo/down/blob/main/src/db/index.ts"
    click StripeWrapper "https://github.com/akshat-owo/down/blob/main/src/lib/stripe.ts"
    click StripeExt "https://github.com/akshat-owo/down/blob/main/src/app/api/webhooks/stripe/route.ts"
    click NextConfig "https://github.com/akshat-owo/down/blob/main/next.config.js"
    click TailwindConfig "https://github.com/akshat-owo/down/blob/main/tailwind.config.ts"
    click PostcssConfig "https://github.com/akshat-owo/down/blob/main/postcss.config.js"
    click GlobalCSS "https://github.com/akshat-owo/down/blob/main/src/app/globals.css"
    click Middleware "https://github.com/akshat-owo/down/blob/main/src/middleware.ts"
    click Utils "https://github.com/akshat-owo/down/blob/main/src/lib/utils.ts"
    click Validator "https://github.com/akshat-owo/down/blob/main/src/lib/validators/sendMessageValidator.ts"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6;
    classDef backend fill:#E8F4FD,stroke:#0366D6;
    classDef lib fill:#F0E6FF,stroke:#6F42C1;
    classDef datastore fill:#E6FFED,stroke:#22863A;
    classDef external fill:#FFF5E5,stroke:#D97706;
    classDef config fill:#F5F5F5,stroke:#6A737D;
    classDef middleware fill:#FFF5F5,stroke:#DBAB09;
```
