# sivaratrisrinivas/chirpy architecture

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

- Interactive diagram: https://gitdiagram.com/sivaratrisrinivas/chirpy
- Repository: https://github.com/sivaratrisrinivas/chirpy

## Overview

##### Project Type and Purpose
- Chirpy is a back-end HTTP server for a microblogging platform concentrating on simplicity, security, and scalability.
- The architecture supports posting short messages (chirps), user management, authentication (login and refresh tokens), as well as integration with an external payment system (Polka) for premium subscriptions (Chirpy Red).

##### Analyzing the File Structure
- Top-level files include server entry points (main.go) and several handler files (handler_chirps_create.go, handler_login.go, etc.) that map to specific API endpoints.
- The "internal" directory organizes core modules such as authentication and database logic.
- The "sql" directory contains raw SQL queries and migration schemas, indicating a strong focus on database versioning and migrations.
- Configuration files (go.mod, go.sum, and sqlc.yaml) indicate dependency management and automated SQL code generation.

##### Key Components
a. Client Layer:
- HTTP clients (browsers, apps) initiating API requests.
b. HTTP Server Layer:
- Router/Mux component handling incoming requests.
- Authentication middleware that verifies user credentials (JWT, password hashing).
- Request handlers that process endpoints involving chirps, users, webhooks, and health checks.
- Metrics component for tracking usage (as indicated by metrics.go).
c. Core Services:
- User Service: For user account creation, management, and updates.
- Chirp Service: For managing posts (chirps) including creation, retrieval, and deletion.
- Auth Service: For login and refresh operations, session/token management.
- Payment Service: Processes external webhooks and integrates with the Polka payment system for Chirpy Red.
d. Database Layer:
- PostgreSQL database represented by multiple tables (Users, Chirps, Refresh Tokens) with defined SQL migrations and query definitions.
e. External Services:
- Polka: The external payment processor integrated via webhooks.

##### Relationships and Interactions
- From the router, show the flow through the Auth middleware to the Request Handlers.
- Core services to the respective database tables (e.g., CRUD operations on Users, Chirps, and managing tokens).

##### Architectural Patterns & Design
- Separation of concerns by clearly separating layers: front door (HTTP server and middleware), business logic (core services), and persistence (database).
- Use of middleware for authentication and traffic control.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        A1("HTTP Client/Browser")
    end

    subgraph "HTTP Server Layer"
        B1("Main Server")
        B2("Router/Mux")
        B3("Auth Middleware")
        B4("Chirp Handler (Create)")
        B5("Chirp Handler (Get)")
        B6("Chirp Handler (Delete)")
        B7("Login Handler")
        B8("Refresh Handler")
        B9("User Create Handler")
        B10("User Update Handler")
        B11("Webhook Handler")
        B12("Metrics")
        B13("Readiness")
        B14("Reset")
    end

    subgraph "Core Services"
        C1("User Service")
        C2("Chirp Service")
        C3("Auth Service")
        C4("Payment Service")
    end

    subgraph "Database Layer"
        D1("Users Table")
        D2("Chirps Table")
        D3("Refresh Tokens Table")
    end

    subgraph "External Services"
        E1("Polka Payment System")
    end

    %% Client to HTTP Server
    A1 --> B2
    B1 --> B2

    %% Endpoints bypassing auth middleware
    B2 --> B7
    B2 --> B8

    %% Endpoints behind auth middleware
    B2 --> B3
    B2 --> B12
    B2 --> B13
    B2 --> B14
    B3 --> B4
    B3 --> B5
    B3 --> B6
    B3 --> B9
    B3 --> B10
    B3 --> B11

    %% Handlers calling core services
    B4 --> C2
    B5 --> C2
    B6 --> C2
    B9 --> C1
    B10 --> C1
    B7 --> C3
    B8 --> C3
    B11 --> C4

    %% Core services interacting with persistence / external services
    C1 --> D1
    C2 --> D2
    C3 --> D3
    C4 --> E1

    %% Click Events - HTTP Server Layer
    click B1 "https://github.com/sivaratrisrinivas/chirpy/blob/main/main.go"
    click B4 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_chirps_create.go"
    click B5 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_chirps_get.go"
    click B6 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_chirps_delete.go"
    click B7 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_login.go"
    click B8 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_refresh.go"
    click B9 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_users_create.go"
    click B10 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_users_update.go"
    click B11 "https://github.com/sivaratrisrinivas/chirpy/blob/main/handler_webhooks.go"
    click B12 "https://github.com/sivaratrisrinivas/chirpy/blob/main/metrics.go"
    click B13 "https://github.com/sivaratrisrinivas/chirpy/blob/main/readiness.go"
    click B14 "https://github.com/sivaratrisrinivas/chirpy/blob/main/reset.go"

    %% Click Events - Authentication Middleware & Auth Service
    click B3 "https://github.com/sivaratrisrinivas/chirpy/blob/main/internal/auth/auth.go"
    click C3 "https://github.com/sivaratrisrinivas/chirpy/blob/main/internal/auth/auth.go"

    %% Click Events - Core Services
    click C2 "https://github.com/sivaratrisrinivas/chirpy/blob/main/internal/database/chirps.sql.go"
    click C1 "https://github.com/sivaratrisrinivas/chirpy/blob/main/internal/database/users.sql.go"
    click C4 "https://github.com/sivaratrisrinivas/chirpy/blob/main/sql/schema/005_chirpy_red.sql"

    %% Click Events - Database Layer
    click D1 "https://github.com/sivaratrisrinivas/chirpy/blob/main/internal/database/models.go"
    click D2 "https://github.com/sivaratrisrinivas/chirpy/blob/main/sql/queries/chirps.sql"
    click D3 "https://github.com/sivaratrisrinivas/chirpy/blob/main/sql/queries/refresh_tokens.sql"

    %% Styles
    class A1 client
    class B1,B2,B3,B4,B5,B6,B7,B8,B9,B10,B11,B12,B13,B14 server
    class C1,C2,C3,C4 service
    class D1,D2,D3 db
    class E1 external

    classDef client fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef server fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef service fill:#ffa07a,stroke:#000,stroke-width:2px;
    classDef db fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
