# ssshogunn/lumina architecture

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

- Interactive diagram: https://gitdiagram.com/ssshogunn/lumina
- Repository: https://github.com/ssshogunn/lumina

## Overview

##### Main Components
- Frontend (User Interface): Notice the Next.js “app” folder under src/app that contains pages (dashboard, auth-callback, etc.) and many React components (Chat, NavBar, Providers, etc.). This is where the user interacts with the system.
- API / Backend Endpoints: The src/app/api directory contains several API route implementations including endpoints for authentication ([kindeAuth]), messages, tRPC calls, and file uploads. These endpoints implement the business logic for file processing, authentication (via KindeAuth), and AI querying.
- Business Logic / Services Layer: The src/lib directory houses modules for file uploading (likely interfacing with AWS S3), OpenAI integration (to handle AI responses), Pinecone vector DB operations (for smart indexing), and generic utilities or validators.
- Database Layer: The presence of a prisma folder (with schema.prisma) and a src/db folder indicates that your application uses Prisma as an ORM to interact with a Postgresql database. According to the README, the actual database service is Supabase.
- External Services: The system integrates with multiple third-party services:
- Authentication: KindeAuth for user sign up/log in.
- AI: OpenAI for generating responses based on PDF content.
- Vector Database: Pinecone for efficient document indexing.
- Cloud Storage: AWS S3 for storing PDF files.

##### Relationships and Data Flow
- Users interact with the Frontend (written in Next.js with React) which is composed of various pages and components.
- Once the user uploads a PDF via the intuitive drag-and-drop upload interface, the frontend calls the API endpoint in /src/app/api/upload. The file is then transferred to AWS S3 and its metadata is stored in the Postgresql database through Prisma.
- In parallel, the PDF content is processed: it’s likely sent to an OpenAI integration (in src/lib/openai.ts) to extract content for conversational use, and then indexed via Pinecone (in src/lib/pinecone.ts) for rapid document retrieval.
- The chat functionality is powered by specific APIs (see /src/app/api/message and TRPC endpoints in /src/app/api/trpc and src/trpc). This ensures the frontend chat components are decoupled but well-integrated with backend logic.
- User authentication flows through a dedicated auth route (/src/app/api/auth/[kindeAuth]) which interacts with KindeAuth externally.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates the frontend UI, API logic, and external integrations (file upload, AI, vector DB) into distinct modules.
- Modular and Component-Based Design: The React components (in src/components) are focused on specific functionalities (Chat, Dashboard, UI components), which can be independently updated or reused.
- API Abstraction with tRPC: The use of tRPC in both the API and client components allows for strongly typed, end-to-end communication.
- Cloud and External Provider Integration: The architectural design embraces multiple external services (KindeAuth, AWS S3, Pinecone, OpenAI) and supports scalable, cloud-based interactions.

##### Technologies, Frameworks, and Libraries
- Next.js with TypeScript for building the full-stack application, including both server-rendered pages and API endpoints.
- Tailwind CSS for styling.
- Prisma as the ORM layer interacting with the Supabase (Postgresql) database.
- External SDKs and libraries for integration with KindeAuth, AWS S3, Pinecone, and OpenAI.
- tRPC for type-safe API communication between the frontend and backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User("User"):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Pages & Layout (Next.js)"]:::frontend
        FE2["React Components"]:::frontend
    end

    %% API Endpoints
    subgraph "API Endpoints"
        API1["Auth Endpoint ([kindeAuth])"]:::api
        API2["Message Endpoint"]:::api
        API3["tRPC Endpoint"]:::api
        API4["File Upload Endpoint"]:::api
    end

    %% Business Logic & Services Layer
    subgraph "Business Logic & Services"
        BL1["File Upload Service (AWS S3)"]:::logic
        BL2["OpenAI Integration"]:::logic
        BL3["Pinecone Integration"]:::logic
        BL4["Utils & Validators"]:::logic
    end

    %% Database Layer
    subgraph "Database Layer"
        DB1["Prisma & Schema"]:::database
        DB2["DB Access (Supabase Postgres)"]:::database
    end

    %% External Services
    subgraph "External Services"
        EXT1["KindeAuth"]:::external
        EXT2["AWS S3"]:::external
        EXT3["OpenAI"]:::external
        EXT4["Pinecone"]:::external
    end

    %% Connections - User Interaction
    User -->|"interacts"| FE1
    User -->|"interacts"| FE2

    %% Frontend calling API Endpoints
    FE1 -->|"authenticate"| API1
    FE1 -->|"uploadPDF"| API4
    FE2 -->|"sendChat"| API2
    FE2 -->|"tRPC call"| API3

    %% API Endpoints calling Business Logic & External Services
    API1 -->|"authCall"| EXT1
    API4 -->|"processFile"| BL1
    API4 -->|"triggerAI"| BL2
    API4 -->|"triggerIndex"| BL3
    API2 -->|"validate"| BL4
    API3 -->|"validate"| BL4

    %% Business Logic interactions
    BL1 -->|"storeFile"| EXT2
    BL1 -->|"saveMeta"| DB2

    %% Database Layer usage
    DB2 -->|"uses"| DB1

    %% Business Logic External flows (for completeness)
    BL2 -->|"calls"| EXT3
    BL3 -->|"calls"| EXT4

    %% Click Events
    click FE1 "https://github.com/ssshogunn/lumina/tree/main/src/app"
    click FE2 "https://github.com/ssshogunn/lumina/tree/main/src/components"
    click API1 "https://github.com/ssshogunn/lumina/blob/main/src/app/api/auth/[kindeAuth]/route.ts"
    click API2 "https://github.com/ssshogunn/lumina/blob/main/src/app/api/message/route.ts"
    click API3 "https://github.com/ssshogunn/lumina/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click API4 "https://github.com/ssshogunn/lumina/blob/main/src/app/api/upload/route.ts"
    click BL1 "https://github.com/ssshogunn/lumina/blob/main/src/lib/file-upload.ts"
    click BL2 "https://github.com/ssshogunn/lumina/blob/main/src/lib/openai.ts"
    click BL3 "https://github.com/ssshogunn/lumina/blob/main/src/lib/pinecone.ts"
    click BL4 "https://github.com/ssshogunn/lumina/blob/main/src/lib/utils.ts"
    click DB1 "https://github.com/ssshogunn/lumina/blob/main/prisma/schema.prisma"
    click DB2 "https://github.com/ssshogunn/lumina/tree/main/src/db"

    %% Styles
    classDef frontend fill:#DDEEFF,stroke:#000,stroke-width:2px;
    classDef api fill:#FFEEDD,stroke:#000,stroke-width:2px;
    classDef logic fill:#FFF0B3,stroke:#000,stroke-width:2px;
    classDef database fill:#E1D5E7,stroke:#000,stroke-width:2px;
    classDef external fill:#F9C1C1,stroke:#000,stroke-width:2px;
```
