# rmadhuram/pcaisso-next architecture

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

- Interactive diagram: https://gitdiagram.com/rmadhuram/pcaisso-next
- Repository: https://github.com/rmadhuram/pcaisso-next

## Overview

##### Project Type and Purpose
- Pcaisso is a full-stack web application built with Next.js that leverages large language models (LLMs) and other AI techniques to generate graphical outputs based on code.
- The project combines frontend components (UI for drawing, blog, FAQ, admin pages) with backend API endpoints (for authentication, drawing, initiating AI requests, and persisting data). Additionally, it includes integrations with external LLM services.

##### Main Components Identification
– Frontend Layer (Client-Side):
- Public Assets & Samples: Static assets in public/ (demos, images, videos) and sample HTML pages in samples/ to showcase graphical outputs.
– API/Backend Layer:
- API Routes: Found in src/app/api covering functionalities like authentication, chat, drawing results, likes, prompts, and admin grouping.
– Business Logic & LLM Integration:
- LLM Modules: In src/lib/llms (get-code.ts, invoke-anthropic.ts, invoke-openai.ts, llm.factory.ts, etc.) which handle the generation and processing of AI-generated graphical code.
– Persistence & Database:
- Database Utilities & Persistence: Located in src/lib/db.ts and src/persistence (with modules for admin, likes, result, user, etc.) which manage data storage and retrieval.
– Utility & Styling:
- Utilities and hooks such as usePubSub, format-time, and calculate-cost found in src/app/utils and src/app/hooks.
- Shared styling files under src/styles and modular SCSS files in respective component folders.
– Configuration & Deployment:
- Important configuration files include next.config.mjs, tsconfig.json, package.json, and .env.template that lay out environment variables and project settings.

- End-user (browser) interacting with the frontend Next.js application.
- The frontend (UI components and pages) makes API calls to backend routes (e.g., API endpoints for drawing, auth, chat).
- The backend layer, upon receiving requests, interacts with the LLM modules in src/lib/llms to generate drawing code/graphics.
- The persistence layer (with database utilities) stores and retrieves data such as drawing results, user likes, and authentication details.
- External services can be indicated (e.g., LLM providers like OpenAI or Anthropic, if applicable).

##### Architectural Patterns and Design Principles
- Next.js File-Based Routing & API Endpoints: Emphasize the separation of UI and API routes.
- Modular Design & Separation of Concerns: Different directories (app, components, api, lib, persistence) indicate discrete roles and modularization.
- Client-Server Data Flow: Clearly mark client requests, server processing, and persistent storage interactions.
- Use of External LLM Services: Highlight the use of patterns (e.g., factory pattern in llm.factory.ts) that abstract LLM service calls.

##### Relevant Technologies and Frameworks
- Frontend: Next.js, React, SCSS for styling.
- Backend: Node.js (via Next.js API routes).
- AI Integration: Custom LLM modules dealing with OpenAI and Anthropic APIs.
- Database: Implied by persistence and db.ts modules (actual database system would be defined in the .env config).
- Utilities: ESLint, TypeScript (given the presence of tsconfig.json and type declarations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        direction TB
        U["User/Browser"]:::user
        FUI["Frontend (Next.js UI)"]:::frontend
        subgraph "Utilities & Styling"
            direction TB
            UTILS_H["Hooks"]:::utils
            UTILS_U["Utils"]:::utils
            UTILS_S["Styles"]:::utils
        end
        subgraph "Public Assets & Samples"
            direction TB
            PUBLIC["Public Assets"]:::public
            SAMPLES["Samples"]:::public
        end
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        API["API Endpoints"]:::backend
        LLM["LLM Integration Module"]:::backend
        subgraph "Persistence & Database Integration"
            direction TB
            DB1["DB Utility"]:::database
            DB2["Persistence Modules"]:::database
        end
    end

    %% External Services
    EXT["External LLM Services"]:::external

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        direction TB
        CONF1[".env.template"]:::config
        CONF2["next.config.mjs"]:::config
        CONF3["tsconfig.json"]:::config
        CONF4["package.json"]:::config
    end

    %% Connections
    U --> FUI
    FUI -->|"calls"| API
    API -->|"invokes"| LLM
    API <-->|"stores/retrieves"| DB1
    API <-->|"stores/retrieves"| DB2
    LLM -->|"calls"| EXT
    PUBLIC -->|"serves static"| FUI
    SAMPLES -->|"provides examples"| FUI
    CONF1 --- FUI
    CONF2 --- FUI
    CONF3 --- API
    CONF4 --- API

    %% Styles
    classDef user fill:#FFFAE6,stroke:#B8860B,stroke-width:2px;
    classDef frontend fill:#D0E6FF,stroke:#045FB4,stroke-width:2px;
    classDef backend fill:#FFF2CC,stroke:#D2691E,stroke-width:2px;
    classDef database fill:#FFD1DC,stroke:#C1232B,stroke-width:2px;
    classDef external fill:#DFFFD6,stroke:#2E8B57,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#483D8B,stroke-width:2px;
    classDef utils fill:#F0FFF0,stroke:#228B22,stroke-width:2px;
    classDef public fill:#FFF0F5,stroke:#C71585,stroke-width:2px;

    %% Click Events for Component Mapping
    click FUI "https://github.com/rmadhuram/pcaisso-next/tree/main/src/app"
    click API "https://github.com/rmadhuram/pcaisso-next/tree/main/src/app/api"
    click LLM "https://github.com/rmadhuram/pcaisso-next/tree/main/src/lib/llms"
    click DB1 "https://github.com/rmadhuram/pcaisso-next/blob/main/src/lib/db.ts"
    click DB2 "https://github.com/rmadhuram/pcaisso-next/tree/main/src/persistence"
    click UTILS_H "https://github.com/rmadhuram/pcaisso-next/tree/main/src/app/hooks"
    click UTILS_U "https://github.com/rmadhuram/pcaisso-next/tree/main/src/app/utils"
    click UTILS_S "https://github.com/rmadhuram/pcaisso-next/tree/main/src/styles"
    click PUBLIC "https://github.com/rmadhuram/pcaisso-next/tree/main/public"
    click SAMPLES "https://github.com/rmadhuram/pcaisso-next/tree/main/samples"
    click CONF1 "https://github.com/rmadhuram/pcaisso-next/blob/main/.env.template"
    click CONF2 "https://github.com/rmadhuram/pcaisso-next/blob/main/next.config.mjs"
    click CONF3 "https://github.com/rmadhuram/pcaisso-next/blob/main/tsconfig.json"
    click CONF4 "https://github.com/rmadhuram/pcaisso-next/blob/main/package.json"
```
