# melkeydev/yappr architecture

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

- Interactive diagram: https://gitdiagram.com/melkeydev/yappr
- Repository: https://github.com/melkeydev/yappr

## Overview

##### Project type and purpose
- This is a full-stack, real-time, ephemeral chat application (“Yappr”).
- Frontend: React + TypeScript + Vite + Tailwind CSS
- Backend: Go (Chi router, Gorilla WebSocket) + PostgreSQL
- Key features: ephemeral rooms (24-hour auto-expiration), daily pinned topics (via HackerNews/Reddit), user accounts & anonymous chat, WebSocket messaging, achievement tracking.

##### File structure
- Top-level:
- docker-compose.yml / docker-compose-prod.yml
- client/ (React app)
- server/ (Go service)
- client/:
- src/pages, components, hooks, context, api (auth, rooms, stats), assets
- Vite config, environment, Dockerfiles (dev & prod)
- server/:
- internal/
– api/handler (core, user, stats) & model
– repo (room, user, stats)
– service (user, stats, pinnedrooms, topics)
– ws (client management, core pub/sub)
– filter (profanity)
- router/router.go, middleware (auth), util (env, cookies, response)
- db migrations + db.go to apply them
- Dockerfiles (dev & prod), main.go, go.mod

##### README for additional insights
- Tech stack callouts and environment variables for JWT, API base, WebSocket URL.
- Quick-start using Docker Compose for local dev.
- Daily pinned room topics fetched from external services (Reddit & HackerNews).

a. Main components
- Browser Client (React SPA)
- API Gateway / HTTP Server (Chi router + middleware)
- WebSocket Hub (Gorilla WebSocket core + client manager)
- Business-Logic Services (User, Stats, Topics, PinnedRooms)
- Data Access Layer / Repositories (User, Room, Stats)
- PostgreSQL Database
- External Topic Providers (Reddit API, HackerNews API)
- (Optional) Reverse Proxy / Load Balancer if scaling (Nginx, ALB)
b. Relationships & interactions
1. Client → HTTP REST calls → API Gateway (login, signup, fetch rooms, stats) → Services → Repositories → Database
2. Client ↔ WebSocket → WebSocket Hub → Core service broadcasts to other clients
3. PinnedTopics service (cron or startup) → fetch external APIs → populate pinned rooms in DB
4. Migrations apply via migrate.go on startup → ensure schema up-to-date
c. Architectural patterns & design principles
- Layered architecture (handlers → services → repositories → DB)
- Dependency injection via internal package separation
- CQRS-style separation: REST for CRUD, WebSocket for real-time updates
- Ephemeral data: TTL logic in service or scheduled cleanup for 24-hour room expiry
- External integration: “Topics” service decouples fetching pinned topics
d. Key technologies/frameworks
- Go + Chi router + Gorilla WebSocket
- React + Vite + TypeScript + Tailwind
- PostgreSQL (with Go migrations)
- Docker / Docker Compose for containerization

##### Essential details to capture
- Separation of concerns: show handlers → services → repos → DB
- WebSocket client registration and broadcast path
- Data TTL/cleanup for ephemeral rooms
- External topic fetch schedule or trigger
- Migration step before DB use

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    BrowserClient["Browser Client (React SPA)"]:::frontend
    click BrowserClient "https://github.com/melkeydev/yappr/tree/main/client/"

    %% Backend Entry Points
    subgraph "API Layer"
        HTTPAPI["HTTP API Gateway"]:::api
        click HTTPAPI "https://github.com/melkeydev/yappr/blob/main/server/router/router.go"
        AuthHandler["Auth Handler"]:::handler
        click AuthHandler "https://github.com/melkeydev/yappr/blob/main/server/internal/api/handler/user/user.go"
        StatsHandler["Stats Handler"]:::handler
        click StatsHandler "https://github.com/melkeydev/yappr/blob/main/server/internal/api/handler/stats/stats.go"
    end

    subgraph "WebSocket Hub"
        WSCore["WS Core"]:::ws
        click WSCore "https://github.com/melkeydev/yappr/blob/main/server/internal/ws/core.go"
        WSClient["WS Client Manager"]:::ws
        click WSClient "https://github.com/melkeydev/yappr/blob/main/server/internal/ws/client.go"
    end

    %% Services
    subgraph "Business Services"
        AuthService["Auth Service"]:::service
        click AuthService "https://github.com/melkeydev/yappr/blob/main/server/internal/service/user/user.go"
        StatsService["Stats Service"]:::service
        click StatsService "https://github.com/melkeydev/yappr/blob/main/server/internal/service/stats/stats.go"
        TopicsService["Topics Service"]:::service
        click TopicsService "https://github.com/melkeydev/yappr/blob/main/server/internal/service/topics/topics.go"
        PinnedRooms["PinnedRooms Service"]:::service
        click PinnedRooms "https://github.com/melkeydev/yappr/blob/main/server/internal/service/pinnedrooms/pinnedrooms.go"
    end

    %% Repositories
    subgraph "Data Repositories"
        UserRepo["User Repo"]:::repo
        click UserRepo "https://github.com/melkeydev/yappr/blob/main/server/internal/repo/user/user.go"
        RoomRepo["Room Repo"]:::repo
        click RoomRepo "https://github.com/melkeydev/yappr/blob/main/server/internal/repo/room/room.go"
        StatsRepo["Stats Repo"]:::repo
        click StatsRepo "https://github.com/melkeydev/yappr/blob/main/server/internal/repo/stats/stats.go"
    end

    %% Database and Migrations
    MigrateGo["Migration Runner"]:::util
    click MigrateGo "https://github.com/melkeydev/yappr/blob/main/server/db/migrate.go"
    MigrationsSQL["SQL Migrations"]:::util
    click MigrationsSQL "https://github.com/melkeydev/yappr/blob/main/server/db/migrations/*.sql"
    Database["PostgreSQL DB"]:::db

    %% Utilities
    subgraph "Utilities"
        EnvUtil["Env Loader"]:::util
        click EnvUtil "https://github.com/melkeydev/yappr/blob/main/server/util/env.go"
        CookiesUtil["Cookie Manager"]:::util
        click CookiesUtil "https://github.com/melkeydev/yappr/blob/main/server/util/cookies.go"
        ResponseUtil["Response Helper"]:::util
        click ResponseUtil "https://github.com/melkeydev/yappr/blob/main/server/util/response.go"
        PasswordUtil["Password Helper"]:::util
        click PasswordUtil "https://github.com/melkeydev/yappr/blob/main/server/util/password.go"
    end

    %% Main entry
    Main["Main Entrypoint"]:::main
    click Main "https://github.com/melkeydev/yappr/blob/main/server/main.go"

    %% External APIs
    RedditAPI["Reddit API"]:::external
    HackerNewsAPI["HackerNews API"]:::external

    %% Flows
    BrowserClient -->|HTTP POST /login| HTTPAPI
    BrowserClient -->|HTTP GET /stats| HTTPAPI
    BrowserClient -->|WS connect /ws| WSCore
    WSCore -->|register client| WSClient
    WSCore -->|broadcast message| WSClient
    WSClient -->|send to clients| BrowserClient

    HTTPAPI --> AuthHandler
    HTTPAPI --> StatsHandler

    AuthHandler --> AuthService
    StatsHandler --> StatsService

    AuthService --> UserRepo
    StatsService --> StatsRepo

    UserRepo --> Database
    RoomRepo --> Database
    StatsRepo --> Database

    Main --> MigrateGo
    MigrateGo --> MigrationsSQL
    MigrateGo --> Database

    Main --> TopicsService
    Main --> PinnedRooms

    PinnedRooms -->|daily cron fetch| TopicsService
    PinnedRooms -->|cleanup expired rooms| RoomRepo

    TopicsService -->|fetch topics| RedditAPI
    TopicsService -->|fetch topics| HackerNewsAPI
    TopicsService --> RoomRepo

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#000;
    classDef api fill:#c8e6c9,stroke:#43a047,color:#000;
    classDef ws fill:#d1c4e9,stroke:#8e24aa,color:#000;
    classDef service fill:#ffe082,stroke:#f9a825,color:#000;
    classDef repo fill:#fff9c4,stroke:#fbc02d,color:#000;
    classDef db fill:#ffccbc,stroke:#e64a19,color:#000;
    classDef external fill:#c5cae9,stroke:#3949ab,color:#000;
    classDef handler fill:#a5d6a7,stroke:#2e7d32,color:#000;
    classDef util fill:#eeeeee,stroke:#757575,color:#000;
    classDef main fill:#b3e5fc,stroke:#0288d1,color:#000;
```
