# mtwn105/githubwrapped architecture

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

- Interactive diagram: https://gitdiagram.com/mtwn105/githubwrapped
- Repository: https://github.com/mtwn105/githubwrapped

## Overview

##### Main Components

a) Client Layer:
- Next.js 14 Frontend Application
- Server-Side Components
- Client-Side Components
- API Routes
- Server Actions

b) Backend Layer:
- Spring Boot 3.3 Application
- Authentication Filter
- Controllers
- Services
- Repositories

c) External Services:
- GitHub GraphQL API
- MongoDB Database
- OpenPanel Analytics
- Vercel (Frontend Hosting)
- Fly.io (Backend Hosting)

**┌─ Client Tier ──────────────────────┐**
- Next.js 14 Frontend             │
- TypeScript & Tailwind CSS       │
- Server/Client Components        │
- Server Actions                  │
- ┬──────────────────┘

**┌─ Server Tier ─┴──────────────────┐**
- Spring Boot 3.3                │
- Java 21                        │
- Controllers & Services         │
- Auth Filter                    │
- ┬──────────────────┘

**┌─ Data Tier ───┴──────────────────┐**
- MongoDB                        │
- GitHub GraphQL API             │
- ┘

##### Component Relationships

- Frontend Server Actions → Backend Controllers
- Backend Controllers → Services → Repositories
- Services → GitHub GraphQL API
- Repositories → MongoDB
- API Routes → External Services

##### Specific Implementation Details

Frontend Section:
- Page routes (/[username], /about, /api)
- Components structure
- Server actions for stats fetching
- OG image generation route

Backend Section:
- Controller endpoints
- Service layer with GitHub integration
- Authentication filter
- Repository layer with MongoDB interaction

##### Additional Elements

Supporting components:
- Circuit breaker (Resilience4j)
- Analytics integration (OpenPanel)
- Caching mechanisms
- Authentication flow
- Image generation service

##### Deployment Flow

A separate section showing:
- Vercel deployment for frontend
- Fly.io deployment for backend
- MongoDB Atlas connection
- Environment configurations

##### Notes for Implementation

- Keep the main application flow clear and centered
- Related components together
- Clear boundaries between different services
- Error handling and fallback paths
- Asynchronous operations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Layer"]
        FE["Next.js Frontend"]:::frontend
        SC["Server Components"]:::frontend
        CC["Client Components"]:::frontend
        SA["Server Actions"]:::frontend
        AR["API Routes"]:::frontend
        UI["UI Components"]:::frontend
        AN["Analytics"]:::frontend
    end

    subgraph Server["Server Layer"]
        SB["Spring Boot App"]:::backend
        AF["Auth Filter"]:::security
        CT["Controllers"]:::backend
        SV["Services"]:::backend
        RP["Repositories"]:::backend
        GI["GitHub GraphQL Integration"]:::backend
        DM["Data Models"]:::backend
    end

    subgraph External["External Services"]
        GH["GitHub GraphQL API"]:::external
        MD["MongoDB"]:::database
        OP["OpenPanel Analytics"]:::external
        VE["Vercel"]:::hosting
        FL["Fly.io"]:::hosting
    end

    %% Relationships
    FE --> SA
    FE --> AR
    SA --> CT
    AR --> CT
    AF --> CT
    CT --> SV
    SV --> GI
    GI --> GH
    SV --> RP
    RP --> MD
    AN --> OP
    FE --> VE
    SB --> FL

    %% Click Events
    click FE "https://github.com/mtwn105/GitHubWrapped/tree/main/frontend/"
    click SA "https://github.com/mtwn105/GitHubWrapped/tree/main/frontend/app/actions/"
    click AR "https://github.com/mtwn105/GitHubWrapped/tree/main/frontend/app/api/"
    click UI "https://github.com/mtwn105/GitHubWrapped/tree/main/frontend/components/"
    click AN "https://github.com/mtwn105/GitHubWrapped/blob/main/frontend/lib/analytics.ts"
    click SB "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/"
    click AF "https://github.com/mtwn105/GitHubWrapped/blob/main/backend/src/main/java/dev/amitwani/githubwrapped/auth/AuthFilter.java"
    click CT "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/controller/"
    click SV "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/service/"
    click RP "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/repository/"
    click GI "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/dto/graphql/"
    click DM "https://github.com/mtwn105/GitHubWrapped/tree/main/backend/src/main/java/dev/amitwani/githubwrapped/model/"

    %% Styles
    classDef frontend fill:#2563eb,color:white
    classDef backend fill:#16a34a,color:white
    classDef security fill:#dc2626,color:white
    classDef database fill:#9333ea,color:white
    classDef external fill:#ca8a04,color:white
    classDef hosting fill:#0891b2,color:white

    %% Legend
    subgraph Legend
        L1["Frontend Components"]:::frontend
        L2["Backend Services"]:::backend
        L3["Security"]:::security
        L4["Database"]:::database
        L5["External Services"]:::external
        L6["Hosting"]:::hosting
    end
```
