# owengretzinger/gitreadme architecture

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

- Interactive diagram: https://gitdiagram.com/owengretzinger/gitreadme
- Repository: https://github.com/owengretzinger/gitreadme

## Overview

Based on your provided file tree and README, this project is a full-stack application that focuses on generating high-quality README files for repositories via an AI process. The system consists of a Next.js application that handles both the frontend and backend (via Next.js API routes and tRPC), along with a separate Python-based repo packing service that pre-processes repository data.

##### Main Components
- Frontend Application: Represent the Next.js client-side portion that includes UI components (built with Shadcn UI, Tailwind CSS, and Next-themes) and routing under the “src/app” directory. It handles user interactions such as providing a repository URL, selecting a template, and managing authentication (via NextAuth.js).
- Backend API & Business Logic: Identify the Next.js backend part, including API routes, tRPC endpoints, and server-side logic. Highlight components for user authentication, dashboard management, and the handling of README generation requests (using endpoints under “src/app/api” and “src/server”).
- Database Layer: Illustrate the Postgres database (hosted on Neon) and note the usage of Drizzle ORM along with migration scripts and SQL files (from the “drizzle” and “migrations” folders). Make it clear that this layer stores generated README files, user data, and other persistent settings.
- Repo Packing Service: Include the Python-based microservice (found in the “repo-packer” folder) which leverages gitingest. This service acts as a standalone component and is authenticated via an environment token (REPO_PACKER_TOKEN) to communicate with the Next.js app. It prepares the repository data by excluding files/folders and feeding pre-processed information to the main app.
- External Services/Integrations: Identify third-party services that the project depends on, such as:
- Google Cloud (specifically Vertex AI for AI capabilities and Google Auth for authentication).
- Vercel for deployment
- Neon for hosting the Postgres database

##### Relationships and Interactions
- That the Backend (or possibly the frontend service layer) sends repository URLs, along with any exclusion instructions, to the Repo Packing Service. A secure channel (with the REPO_PACKER_TOKEN) should be noted, and data flows from the Next.js backend to the repo packing service and back.
- Integrations with external services such as Google Cloud (for Vertex AI and authentication) and any synchonization with Vercel/Neon.

##### Architectural Patterns
- Separation of concerns between the frontend UI and backend logic.
- Use of tRPC for type-safe remote procedure calls.
- That the Python-based repo packing service is decoupled from the main application, making it a microservice or standalone worker that can be independently deployed/scaled.
- Mention the use of modern front-end frameworks that support server components (Next.js) and design system components (Shadcn UI, Tailwind CSS).

##### Technologies, Frameworks, and Libraries
- Next.js (with TypeScript) for both frontend and backend.
- tRPC for communication between frontend and backend.
- Drizzle ORM (with its migrations) for database management.
- Postgres as the database (hosted on Neon).
- NextAuth.js for user authentication.
- Shadcn UI, Tailwind CSS, Next-themes for building and theming the user interface.
- Python (using gitingest) for the Repo Packing Service.
- External APIs like Google Cloud’s Vertex AI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend Application (Next.js UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["API Routes"]:::backend
        SRV["Server Logic"]:::backend
        API -->|"Internal_call"| SRV
    end

    %% Database Layer
    subgraph "Database Layer"
        DB1["Drizzle ORM"]:::database
        DBA["Migrations"]:::database
        DB1 -->|"runs_migrations"| DBA
    end

    %% Repo Packing Service
    subgraph "Repo Packing Service"
        RP["Repo Packing Service (Python)"]:::microservice
    end

    %% External Services
    subgraph "External Services"
        GC["Google Cloud (VertexAI/Auth)"]:::external
        VC["Vercel Deployment"]:::external
        NE["Neon (Postgres Hosting)"]:::external
    end

    %% Data Flow Connections
    User -->|"initiates_request"| FE
    FE -->|"tRPC/API_call"| API
    SRV -->|"database_query"| DB1
    SRV -->|"sends_repo_URL_with_token"| RP
    RP -->|"returns_processed_data"| SRV
    SRV -->|"calls_AI"| GC
    API -->|"deployed_on"| VC
    DB1 -->|"hosted_on"| NE

    %% Click Events
    click FE "https://github.com/owengretzinger/gitreadme/tree/main/nextjs/src/app"
    click API "https://github.com/owengretzinger/gitreadme/tree/main/nextjs/src/app/api"
    click SRV "https://github.com/owengretzinger/gitreadme/tree/main/nextjs/src/server"
    click DB1 "https://github.com/owengretzinger/gitreadme/tree/main/nextjs/drizzle"
    click DBA "https://github.com/owengretzinger/gitreadme/tree/main/nextjs/migrations"
    click RP "https://github.com/owengretzinger/gitreadme/tree/main/repo-packer"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px,rx:5,ry:5;
    classDef database fill:#FFB347,stroke:#000,stroke-width:2px,stroke-dasharray: 5,5;
    classDef microservice fill:#FF6961,stroke:#000,stroke-width:2px,rx:5,ry:5;
    classDef external fill:#FDFD96,stroke:#000,stroke-width:2px,stroke-dasharray: 2,2;
```
