# samridhvaasu/stackalchemy architecture

> Architecture diagram of the GitHub repository samridhvaasu/stackalchemy, 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/samridhvaasu/stackalchemy
- Repository: https://github.com/samridhvaasu/stackalchemy

## Overview

##### Main Components
- Frontend: Represent the Next.js application (components, app directory, authentication pages) as the client-side UI. Indicate that it incorporates technologies such as React, Tailwind CSS, and shadcn/ui.
- API Layer: Illustrate the use of a tRPC API router which handles all client-server communication. This sits between the frontend and the server-side business logic.
- Server/Business Logic: Include distinct components for:
- Project Service: Responsible for processing repository information and managing project-related functions.
- GitHub Integration: Handles fetching repository data via GitHub APIs.
- AI Question-Answering: Processes natural language queries and interfaces with an external AI model for generating contextual responses.
- Persistence: Show the PostgreSQL database, managed with Prisma ORM, where data for projects, users, and Q&A pairs are stored.

##### Relationships and Data Flow
- From the Frontend to the API layer (client-to-server communication).
- API layer forwarding requests to the appropriate business logic component.
- The Project Service getting data from both the GitHub Integration (which communicates with the GitHub API) and the AI Question-Answering module (which receives responses from the AI model).
- Interactions that lead to data storage and retrieval from the database.

##### Architectural Patterns and Design Principles
- That the project applies the modern “app router” architecture from Next.js with clear separation between UI, API, and business logic layers.
- Type-safe nature of endpoints using tRPC, which creates strong contracts between the client and the server.
- Point out the modular design of UI components (organized under src/components/ui) and the dedicated folder for server-side API implementations (src/server/api and src/trpc).

##### Relevant Technologies and Frameworks
- Next.js (React framework)
- tRPC (for API routing and type safety)
- Clerk (for user authentication with multiple providers)
- Prisma with PostgreSQL (for the database)
- Tailwind CSS and shadcn/ui (for styling and UI components)
- External integrations with GitHub and an AI service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        FE("Next.js Frontend"):::frontend
        UI("UI Components"):::ui
    end

    %% API Layer
    subgraph "API Layer"
        API("tRPC API Router"):::api
    end

    %% Service & Business Logic
    subgraph "Service & Business Logic"
        PS("Project Service"):::service
        GI("GitHub Integration"):::service
        AI("AI Q&A Service"):::service
    end

    %% Persistence
    DB("Database (PostgreSQL via Prisma)"):::db

    %% External Services
    subgraph "External Services"
        GAPI("GitHub API"):::external
        AIM("AI Model"):::external
    end

    %% Data Flow
    FE -->|"callsAPI"| API
    FE -->|"renders"| UI
    API -->|"invokes"| PS
    API -->|"invokes"| GI
    API -->|"invokes"| AI
    PS -->|"storesRetrieves"| DB
    PS -->|"integratesWith"| GI
    PS -->|"integratesWith"| AI
    GI -->|"fetchesFrom"| GAPI
    AI -->|"queries"| AIM

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ui fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef api fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef service fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef db fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click FE "https://github.com/samridhvaasu/stackalchemy/tree/master/src/app"
    click API "https://github.com/samridhvaasu/stackalchemy/blob/master/src/app/api/trpc/[trpc]/route.ts"
    click API "https://github.com/samridhvaasu/stackalchemy/blob/master/src/server/api/trpc.ts"
    click PS "https://github.com/samridhvaasu/stackalchemy/blob/master/src/server/api/routers/project.ts"
    click GI "https://github.com/samridhvaasu/stackalchemy/blob/master/src/lib/github-loader.ts"
    click GI "https://github.com/samridhvaasu/stackalchemy/blob/master/src/lib/github.ts"
    click AI "https://github.com/samridhvaasu/stackalchemy/blob/master/src/app/(protected)/qa/page.tsx"
    click AI "https://github.com/samridhvaasu/stackalchemy/blob/master/src/app/(protected)/dashboard/ask-question-card.tsx"
    click DB "https://github.com/samridhvaasu/stackalchemy/blob/master/prisma/schema.prisma"
    click UI "https://github.com/samridhvaasu/stackalchemy/tree/master/src/components/ui"
```
