# krish120003/gitfaster architecture

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

- Interactive diagram: https://gitdiagram.com/krish120003/gitfaster
- Repository: https://github.com/krish120003/gitfaster

## Overview

##### Project type and purpose
- Gitfaster is a full‑stack Next.js application (“Built With Next.js”) that provides a modern GitHub client UI with prefetching and caching.
- It uses React components under `src/app` and `src/components`, an API layer under `src/app/api` and `src/server/api`, and interacts with GitHub and a local database/cache.

##### File structure
- Frontend:
– `src/app` directory (Next.js App Router pages & layouts)
– `src/components` (reusable UI elements)
– `src/trpc/react.tsx` & `src/trpc/query-client.ts` (tRPC client setup)
– `src/styles/globals.css`
- Backend/API:
– Next.js API routes in `src/app/api/*` (NextAuth and tRPC routes)
– tRPC server code in `src/server/api/routers/*` (GitHub, issues, PRs, user)
– `src/server/auth` (NextAuth config)
– `src/server/db` (Drizzle/DB schema & client)
– `src/server/redis` (cache client)
– `src/server/github/auth.ts` (GitHub OAuth & token management)
- Config & infra:
– `next.config.js`, `drizzle.config.ts`, `.env.example`, `start-database.sh`
– `package.json`/`pnpm-lock.yaml` for dependencies

##### README for additional insights
- Minimal, performance‑oriented client with prefetching and caching layers.

##### Main components and their interactions
a. Frontend (Browser)
– Next.js React UI (pages + components)
– tRPC client & NextAuth session provider
– Data fetching via tRPC hooks and REST for NextAuth
b. Next.js Server (SSR/API layer)
– NextAuth route (`/api/auth/[...nextauth]`) for login/session
– tRPC HTTP route (`/api/trpc/[trpc]`) forwarding client RPC calls
– SSR handlers for page rendering
c. Application Services
– tRPC routers:
- github.ts (wraps GitHub REST API calls)
- issues.ts, pull-requests.ts, user.ts, post.ts
– Auth service: exchanges OAuth code, issues JWT/session
– Database (Drizzle ORM)
– Redis cache for prefetching/caching responses
d. External Dependencies
– GitHub REST API
– Postgres (or other SQL) started via `start-database.sh`
– Redis instance

##### Architectural patterns & design principles
- Componentized UI (React + Next.js App Router)
- RPC pattern with tRPC (type safety between client/server)
- Separation of concerns: UI ↔ tRPC ↔ Service layer ↔ Data layer
- Caching layer (Redis) sits between service layer and external API/DB
- Auth isolation: NextAuth + GitHub OAuth in a distinct module
- Infrastructure as code: shell script to spin up DB

## Diagram (Mermaid)

```mermaid
graph TB
    %% Browser (Frontend Layer)
    subgraph "Browser (Frontend)"
        direction TB
        UI["Next.js App Router (pages & layouts)"]:::frontend
        Components["Reusable UI Components"]:::frontend
        Styles["Global Styles (globals.css)"]:::frontend
        TRPCClient["tRPC Client Setup"]:::frontend
        SessionProv["NextAuth Session Provider"]:::frontend
    end

    %% Next.js Server (SSR + API Layer)
    subgraph "Next.js Server (SSR + API)"
        direction TB
        NextAuthRoute["NextAuth API Route<br/>(/api/auth/[...nextauth])"]:::backend
        TRPCRoute["tRPC HTTP Route<br/>(/api/trpc/[trpc])"]:::backend
    end

    %% Service & Data Layer
    subgraph "Service & Data Layer"
        direction TB
        TRPCServer["tRPC Server Entry Point"]:::backend
        RootRouter["Root tRPC Router Composition"]:::backend
        subgraph "tRPC Routers"
            direction TB
            GitHubRouter["GitHub API Router"]:::backend
            IssuesRouter["Issues Router"]:::backend
            PullRouter["Pull Requests Router"]:::backend
            UserRouter["User Router"]:::backend
            PostRouter["Post Router"]:::backend
        end
        AuthConfig["NextAuth Config & Service"]:::backend
        GitHubAuth["GitHub OAuth Helper"]:::backend
        DBClient["Drizzle ORM Client & Schema"]:::datastore
        RedisClient["Redis Cache Client"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub REST API"]:::external
        Postgres["Postgres Database"]:::datastore
        RedisStore["Redis Instance"]:::datastore
    end

    %% Connections
    UI -->|"uses RPC hooks"| TRPCClient
    UI -->|"provides session"| SessionProv
    TRPCClient -->|"RPC (HTTP/JSON)"| TRPCRoute
    SessionProv -->|"REST (HTTP)"| NextAuthRoute

    NextAuthRoute -->|"invokes"| AuthConfig
    AuthConfig -->|"reads/writes"| DBClient
    DBClient -->|"persistent storage"| Postgres

    TRPCRoute -->|"forwards RPC"| TRPCServer
    TRPCServer -->|"composes routers"| RootRouter
    RootRouter --> GitHubRouter
    RootRouter --> IssuesRouter
    RootRouter --> PullRouter
    RootRouter --> UserRouter
    RootRouter --> PostRouter

    GitHubRouter -->|"cache lookup/write"| RedisClient
    RedisClient -->|"cache store"| RedisStore
    GitHubRouter -->|"API calls"| GitHubAPI

    IssuesRouter -->|"persistent storage"| DBClient
    PullRouter -->|"persistent storage"| DBClient
    UserRouter -->|"persistent storage"| DBClient
    PostRouter -->|"persistent storage"| DBClient

    GitHubAuth -->|"OAuth flow"| GitHubAPI

    %% Click Events
    click UI "https://github.com/krish120003/gitfaster/tree/main/src/app"
    click Components "https://github.com/krish120003/gitfaster/tree/main/src/components"
    click Styles "https://github.com/krish120003/gitfaster/blob/main/src/styles/globals.css"
    click TRPCClient "https://github.com/krish120003/gitfaster/blob/main/src/trpc/query-client.ts"
    click TRPCClient "https://github.com/krish120003/gitfaster/blob/main/src/trpc/react.tsx"
    click SessionProv "https://github.com/krish120003/gitfaster/blob/main/src/components/session-provider.tsx"
    click NextAuthRoute "https://github.com/krish120003/gitfaster/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click TRPCRoute "https://github.com/krish120003/gitfaster/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click TRPCServer "https://github.com/krish120003/gitfaster/blob/main/src/server/api/trpc.ts"
    click GitHubRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/routers/github.ts"
    click IssuesRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/routers/issues.ts"
    click PullRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/routers/pull-requests.ts"
    click UserRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/routers/user.ts"
    click PostRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/routers/post.ts"
    click RootRouter "https://github.com/krish120003/gitfaster/blob/main/src/server/api/root.ts"
    click AuthConfig "https://github.com/krish120003/gitfaster/blob/main/src/server/auth/config.ts"
    click AuthConfig "https://github.com/krish120003/gitfaster/blob/main/src/server/auth/index.ts"
    click GitHubAuth "https://github.com/krish120003/gitfaster/blob/main/src/server/github/auth.ts"
    click DBClient "https://github.com/krish120003/gitfaster/blob/main/src/server/db/index.ts"
    click DBClient "https://github.com/krish120003/gitfaster/blob/main/src/server/db/schema.ts"
    click DBClient "https://github.com/krish120003/gitfaster/blob/main/drizzle.config.ts"
    click RedisClient "https://github.com/krish120003/gitfaster/blob/main/src/server/redis/index.ts"
    click Postgres "https://github.com/krish120003/gitfaster/blob/main/start-database.sh"
    click Postgres "https://github.com/krish120003/gitfaster/blob/main/.env.example"
    click UI "https://github.com/krish120003/gitfaster/blob/main/package.json"
    click UI "https://github.com/krish120003/gitfaster/blob/main/pnpm-lock.yaml"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366d6,color:#000
    classDef backend fill:#D0FFD6,stroke:#28a745,color:#000
    classDef datastore fill:#EEEEEE,stroke:#666666,color:#000
    classDef external fill:#F5F5F5,stroke:#999999,color:#000
```
