# ramzygirgis/feed-aggregator architecture

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

- Interactive diagram: https://gitdiagram.com/ramzygirgis/feed-aggregator
- Repository: https://github.com/ramzygirgis/feed-aggregator
- Video tour (about a minute): https://gitdiagram.com/ramzygirgis/feed-aggregator/video

## Overview

This is a Go CLI for managing users, RSS feeds and subscriptions, polling feeds into PostgreSQL, and browsing collected posts. The primary workflow is: a user adds/follows feeds, the `agg` command selects feeds due for polling, fetches and parses RSS items, stores URL-deduplicated posts, and `browse` retrieves posts for followed feeds. The graph reflects the documented command capabilities; source excerpts establish the main dispatch, polling, parsing and query paths, while some generated query implementations were not sampled.

Main entry points: [`commands.go`](https://github.com/ramzygirgis/feed-aggregator/blob/main/commands.go) (Command handlers), [`internal/database/db.go`](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/db.go) (Typed query layer), [`main.go`](https://github.com/ramzygirgis/feed-aggregator/blob/main/main.go) (Startup and dispatch), [`middleware.go`](https://github.com/ramzygirgis/feed-aggregator/blob/main/middleware.go) (Login middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and commands"]
  node_entry["Startup and dispatch<br/>[main.go]"]
  node_handlers["Command handlers<br/>[commands.go]"]
end

subgraph group_feeds["Feed collection"]
  node_rss["RSS fetch and parse<br/>[rss_feed.go]"]
end

subgraph group_data["Persistence"]
  node_queryapi["Typed query layer<br/>[db.go]"]
  node_userqueries["User queries<br/>[users.sql.go]"]
  node_feedqueries["Feed and follow queries<br/>[feeds.sql.go]"]
  node_followqueries["Follow queries"]
  node_postqueries["Post queries<br/>[posts.sql.go]"]
  node_schema["Relational schema"]
end

subgraph group_identity["User context"]
  node_auth["Login middleware<br/>[middleware.go]"]
  node_config["Config reader/writer<br/>[configuration.go]"]
  node_configfile["JSON config file"]
end

node_operator(("CLI user"))
node_publisher(("RSS feed servers"))
node_postgres[("PostgreSQL")]

node_operator -->|"runs command"| node_entry
node_entry -->|"loads config"| node_config
node_entry -->|"opens database"| node_queryapi
node_entry -->|"dispatches"| node_handlers
node_config -->|"reads/writes"| node_configfile
node_handlers -->|"sets active user"| node_config
node_handlers -->|"registers protected handlers"| node_auth
node_auth -->|"looks up current user"| node_userqueries
node_auth -->|"delegates authenticated"| node_handlers
node_handlers -->|"manages users"| node_userqueries
node_handlers -->|"selects and updates feeds"| node_feedqueries
node_handlers -->|"manages subscriptions"| node_followqueries
node_handlers -->|"stores and browses posts"| node_postqueries
node_handlers -->|"fetches selected feed"| node_rss
node_rss -->|"requests RSS"| node_publisher
node_queryapi -->|"executes queries"| node_postgres
node_userqueries -->|"uses"| node_queryapi
node_feedqueries -->|"uses"| node_queryapi
node_followqueries -->|"uses"| node_queryapi
node_postqueries -->|"uses"| node_queryapi
node_schema -->|"defines tables"| node_postgres

click node_entry "https://github.com/ramzygirgis/feed-aggregator/blob/main/main.go"
click node_handlers "https://github.com/ramzygirgis/feed-aggregator/blob/main/commands.go"
click node_auth "https://github.com/ramzygirgis/feed-aggregator/blob/main/middleware.go"
click node_config "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/config/configuration.go"
click node_rss "https://github.com/ramzygirgis/feed-aggregator/blob/main/rss_feed.go"
click node_queryapi "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/db.go"
click node_userqueries "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/users.sql.go"
click node_feedqueries "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/feeds.sql.go"
click node_followqueries "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/feed_follows.sql.go"
click node_postqueries "https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/posts.sql.go"
click node_schema "https://github.com/ramzygirgis/feed-aggregator/tree/main/sql/schema"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_handlers,node_operator toneBlue
class node_rss,node_postgres toneAmber
class node_queryapi,node_userqueries,node_feedqueries,node_followqueries,node_postqueries,node_schema,node_publisher toneMint
class node_auth,node_config,node_configfile toneRose
```

## Components

### CLI and commands

- [Startup and dispatch](https://github.com/ramzygirgis/feed-aggregator/blob/main/main.go): `main.go`
- [Command handlers](https://github.com/ramzygirgis/feed-aggregator/blob/main/commands.go): `commands.go`

### Feed collection

- [RSS fetch and parse](https://github.com/ramzygirgis/feed-aggregator/blob/main/rss_feed.go): `rss_feed.go`

### Persistence

- [Typed query layer](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/db.go): `internal/database/db.go`
- [User queries](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/users.sql.go): `internal/database/users.sql.go`
- [Feed and follow queries](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/feeds.sql.go): `internal/database/feeds.sql.go`
- [Follow queries](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/feed_follows.sql.go): `internal/database/feed_follows.sql.go`
- [Post queries](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/database/posts.sql.go): `internal/database/posts.sql.go`
- [Relational schema](https://github.com/ramzygirgis/feed-aggregator/tree/main/sql/schema): `sql/schema`

### User context

- [Login middleware](https://github.com/ramzygirgis/feed-aggregator/blob/main/middleware.go): `middleware.go`
- [Config reader/writer](https://github.com/ramzygirgis/feed-aggregator/blob/main/internal/config/configuration.go): `internal/config/configuration.go`
- **JSON config file**

### Other components

- **CLI user**
- **RSS feed servers**
- **PostgreSQL**

## Connections

- CLI user → Startup and dispatch: runs command
- Startup and dispatch → Config reader/writer: loads config
- Startup and dispatch → Typed query layer: opens database
- Startup and dispatch → Command handlers: dispatches
- Config reader/writer → JSON config file: reads/writes
- Command handlers → Config reader/writer: sets active user
- Command handlers → Login middleware: registers protected handlers
- Login middleware → User queries: looks up current user
- Login middleware → Command handlers: delegates authenticated
- Command handlers → User queries: manages users
- Command handlers → Feed and follow queries: selects and updates feeds
- Command handlers → Follow queries: manages subscriptions
- Command handlers → Post queries: stores and browses posts
- Command handlers → RSS fetch and parse: fetches selected feed
- RSS fetch and parse → RSS feed servers: requests RSS
- Typed query layer → PostgreSQL: executes queries
- User queries → Typed query layer: uses
- Feed and follow queries → Typed query layer: uses
- Follow queries → Typed query layer: uses
- Post queries → Typed query layer: uses
- Relational schema → PostgreSQL: defines tables