# carlosetorresm/rss_aggregator_expl architecture

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

- Interactive diagram: https://gitdiagram.com/carlosetorresm/rss_aggregator_expl
- Repository: https://github.com/carlosetorresm/rss_aggregator_expl

## Overview

##### Project type and purpose
- This is a Go‐based backend service (“RSS Aggregator Example”) that exposes an HTTP API to manage users, subscribe to RSS feeds, fetch and scrape feed items, and persist them in a PostgreSQL database.
- It's intended to run in Docker (via `docker-compose.yaml`), with migrations managed by Goose and SQL queries generated by SQLC.

##### File structure
- At the root:
- `main.go` – application entrypoint (HTTP server setup).
- `handler_*.go` – HTTP handlers for users, feeds, follows, readiness, error handling.
- `middleware_auth.go` – JWT or API‐key auth middleware.
- `scapper.go` & `rss.go` – RSS fetching and parsing logic.
- `json.go`, `models.go` – shared models / DTOs.
- `internal/auth`, `internal/database` – core packages: auth logic, database connectivity, SQLC‐generated models and queries.
- `sql/schema` & `sql/queries` – raw SQL migrations and query templates.
- `docker-compose.yaml`, `.env.template` – container orchestration, environment config.

##### Extract architecture insights from the README
- Exposes REST endpoints to: create users, add/remove RSS sources, subscribe/unsubscribe, scrape content.
- Data is stored in PostgreSQL, which runs in Docker.
- Goose applies schema migrations; SQLC generates type‐safe query code.

##### Main components
a. HTTP/API Layer
- API Gateway / HTTP Router (Go’s `net/http` or a router like `chi`/`mux` if used).
- Authentication Middleware (API Key / JWT).
- Handler Modules (User, Feed, Follow, Readiness, Error).
b. Business Logic Layer
- RSS Scraper (`scapper.go`), Parser (`rss.go`).
- Service functions tying handlers to the database layer.
c. Data Access Layer
- `internal/database` – DB connection pool, SQLC‐generated query methods (`feeds.sql.go`, `users.sql.go`, etc.), migration management.
d. Database
- PostgreSQL container (defined in `docker-compose.yaml`).
- Schema versions (001–006 .sql files under `sql/schema`).
e. External Systems
- Third‐party RSS feed endpoints (HTTP).
f. Dev/Ops Artifacts
- Docker Compose (service definitions).
- Goose migrations.
- SQLC code generation.

##### Relationships and data flows
- Clients→HTTP Router→Auth Middleware→Handler→Business Logic→DB Layer→PostgreSQL.
- Scraper logic invoked either on‐demand via an endpoint or a background job → fetches RSS feed via HTTP → parses items → persists via SQLC queries.
- Handlers orchestrate calls to both the scraper and the DB layer.

##### Architectural patterns & design principles
- Layered Architecture: clear separation between HTTP handlers, business logic, and data access.
- Dependency Injection: pass DB clients and config from `main.go` into internal packages.
- Single Responsibility: each `handler_*.go` focuses on one resource.
- Infrastructure as Code: Docker Compose for the PostgreSQL service; Goose for migrations; SQLC for query codegen.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Boundary
    subgraph "Docker Compose" 
        style DockerCompose fill:none,stroke:#aaa,stroke-dasharray: 5 5
        DockerComposeConfig["docker-compose.yaml"]:::infra
        EnvTemplate[".env.template"]:::infra
        subgraph "Services"
            BackendService["Go Backend Service"]:::service
            PostgreSQL["PostgreSQL"]:::db
        end
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        APIGateway["API Gateway / HTTP Router (main.go)"]:::api
        AuthMiddleware["Authentication Middleware"]:::api
        ErrorHandler["Error Handling Module"]:::api
        UserHandler["User Handler Module"]:::api
        FeedHandler["Feed Handler Module"]:::api
        FeedFollowHandler["Feed-Follow Handler Module"]:::api
        ReadinessHandler["Readiness Handler Module"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic" 
        direction TB
        RSSScraper["RSS Scraper Logic"]:::logic
        RSSParser["RSS Parsing Logic"]:::logic
        AuthLogic["Auth Business Logic"]:::logic
        SharedJSON["Shared JSON Models / DTOs"]:::logic
        SharedModels["Shared Domain Models"]:::logic
    end

    %% Data Access Layer
    subgraph "Data Access" 
        direction TB
        DBInit["Database Connection & Init"]:::data
        subgraph "SQLC-Generated Queries & Models"
            direction TB
            QC_Feeds["feeds.sql.go"]:::data
            QC_Follows["feeds_follows.sql.go"]:::data
            QC_Posts["posts.sql.go"]:::data
            QC_Users["users.sql.go"]:::data
            QC_Models["models.go"]:::data
        end
        subgraph "Raw SQL Templates"
            direction TB
            SQL_Feeds["feeds.sql"]:::infra
            SQL_Follows["feeds_follows.sql"]:::infra
            SQL_Posts["posts.sql"]:::infra
            SQL_Users["users.sql"]:::infra
        end
        subgraph "Goose Migrations"
            direction TB
            Mig1["001_users.sql"]:::infra
            Mig2["002_users_apikey.sql"]:::infra
            Mig3["003_feeds.sql"]:::infra
            Mig4["004_feed_follows.sql"]:::infra
            Mig5["005_feeds_lastfetcheddat.sql"]:::infra
            Mig6["006_posts.sql"]:::infra
        end
        SQLCConfig["sqlc.yaml"]:::infra
    end

    %% External Systems
    subgraph "External RSS Sources" 
        direction TB
        ExternalRSS["RSS Feed Endpoint"]:::external
    end

    %% Connections: Client to API
    Client["Client"]:::external
    Client -->|"HTTP Request"| APIGateway
    APIGateway -->|"Authenticate"| AuthMiddleware
    AuthMiddleware -->|"Handle Errors"| ErrorHandler
    AuthMiddleware -->|"Invoke Handlers"| UserHandler
    AuthMiddleware -->|"Invoke Handlers"| FeedHandler
    AuthMiddleware -->|"Invoke Handlers"| FeedFollowHandler
    AuthMiddleware -->|"Invoke Handlers"| ReadinessHandler

    %% Handlers to Business Logic
    UserHandler -->|"uses"| AuthLogic
    FeedHandler -->|"calls"| RSSScraper
    FeedFollowHandler -->|"calls"| RSSScraper
    ReadinessHandler -->|"checks"| DBInit

    %% Business Logic internals
    RSSScraper -->|"parses"| RSSParser
    RSSParser -->|"uses DTOs"| SharedJSON
    AuthLogic -->|"uses models"| SharedModels

    %% Business Logic to Data Access
    AuthLogic -->|"queries"| QC_Users
    RSSScraper -->|"inserts"| QC_Posts
    RSSScraper -->|"queries"| QC_Feeds
    FeedFollowHandler -->|"queries"| QC_Follows

    %% Data Access to DB
    DBInit -->|"connects"| PostgreSQL
    QC_Users -->|"executes"| PostgreSQL
    QC_Feeds -->|"executes"| PostgreSQL
    QC_Follows -->|"executes"| PostgreSQL
    QC_Posts -->|"executes"| PostgreSQL
    QC_Models -->|"schema introspection"| PostgreSQL
    SQL_Feeds -->|"template for"| QC_Feeds
    SQL_Follows -->|"template for"| QC_Follows
    SQL_Posts -->|"template for"| QC_Posts
    SQL_Users -->|"template for"| QC_Users
    Mig1 -->|"migrates"| PostgreSQL
    Mig2 -->|"migrates"| PostgreSQL
    Mig3 -->|"migrates"| PostgreSQL
    Mig4 -->|"migrates"| PostgreSQL
    Mig5 -->|"migrates"| PostgreSQL
    Mig6 -->|"migrates"| PostgreSQL

    %% Business Logic to External RSS
    RSSScraper -->|"fetch RSS"| ExternalRSS
    ExternalRSS -->|"feed data"| RSSParser

    %% Infra to Services
    DockerComposeConfig --> BackendService
    DockerComposeConfig --> PostgreSQL
    EnvTemplate --> BackendService
    SQLCConfig --> QC_Feeds
    SQLCConfig --> QC_Follows
    SQLCConfig --> QC_Posts
    SQLCConfig --> QC_Users
    SQLCConfig --> QC_Models

    %% Legend (optional)
    classDef api fill:#cde9ff,stroke:#0366d6
    classDef logic fill:#e0ffde,stroke:#28a745
    classDef data fill:#ffe4c0,stroke:#d9730d
    classDef db fill:#f0d6ff,stroke:#7a0c9c,stroke-width:2px
    classDef external fill:#f5f5f5,stroke:#6a737d
    classDef infra fill:#fafbfc,stroke:#586069,stroke-dasharray: 2 2
    classDef service fill:#fff5b1,stroke:#b08800

    %% Click Events
    click APIGateway "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/main.go"
    click AuthMiddleware "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/middleware_auth.go"
    click ErrorHandler "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/handler_err.go"
    click UserHandler "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/handler_user.go"
    click FeedHandler "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/handler_feed.go"
    click FeedFollowHandler "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/handler_feed_follows.go"
    click ReadinessHandler "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/handler_readiness.go"
    click RSSScraper "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/scapper.go"
    click RSSParser "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/rss.go"
    click SharedJSON "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/json.go"
    click SharedModels "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/models.go"
    click AuthLogic "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/auth/auth.go"
    click DBInit "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/db.go"
    click QC_Feeds "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/feeds.sql.go"
    click QC_Follows "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/feeds_follows.sql.go"
    click QC_Posts "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/posts.sql.go"
    click QC_Users "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/users.sql.go"
    click QC_Models "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/internal/database/models.go"
    click SQL_Feeds "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/queries/feeds.sql"
    click SQL_Follows "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/queries/feeds_follows.sql"
    click SQL_Posts "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/queries/posts.sql"
    click SQL_Users "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/queries/users.sql"
    click Mig1 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/001_users.sql"
    click Mig2 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/002_users_apikey.sql"
    click Mig3 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/003_feeds.sql"
    click Mig4 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/004_feed_follows.sql"
    click Mig5 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/005_feeds_lastfetcheddat.sql"
    click Mig6 "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sql/schema/006_posts.sql"
    click DockerComposeConfig "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/docker-compose.yaml"
    click EnvTemplate "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/.env.template"
    click SQLCConfig "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/sqlc.yaml"
    click BackendService "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/go.mod"
    click BackendService "https://github.com/carlosetorresm/rss_aggregator_expl/blob/main/go.sum"
```
