# sharathdoes/daymark architecture

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

- Interactive diagram: https://gitdiagram.com/sharathdoes/daymark
- Repository: https://github.com/sharathdoes/daymark

## Overview

1. **What this service is**
   - Daymark is a Go backend that converts RSS news feeds into category-based quizzes.
   - The core loop is: ingest feeds → scrape full articles → persist them in Postgres → ask Groq to generate multiple-choice questions from recent articles.

2. **Runtime entrypoints**
   - `cmd/api/main.go` is the main HTTP API process.
   - `cmd/workers/worker.go` is a separate background process, and `internal/scheduler/daily_quiz.go` suggests scheduled quiz-related jobs.
   - `cmd/workers/createfeed.js` is an auxiliary worker script, likely used for feed creation/automation outside the main Go API flow.

3. **HTTP/API boundary**
   - The API is built with Gin and organized through `internal/router/router.go`.
   - Each domain module exposes its own router, handler, service, and repository layer, so the main boundary is the HTTP handler layer versus internal business/data layers.
   - Swagger docs are generated and served from `docs/` for the public API contract.

4. **Main domain modules**
   - `category` manages category CRUD and likely groups feed sources.
   - `feedSource` manages RSS feed sources attached to categories.
   - `articles` handles article persistence and retrieval.
   - `quiz` generates quizzes and stores quiz results.
   - `user` and `subscribe` support user identity and subscription-related flows.

5. **Feed ingestion pipeline**
   - Feed sources are fetched by category, parsed with RSS tooling (`internal/services/rss_service.go` and `pkg/utils/getarticles.go` are likely involved).
   - Feed items become article candidates, then the article page is scraped and cleaned by `internal/services/scraper_service.go`.
   - Articles are deduplicated by URL and written into Postgres through the article repository.

6. **Quiz generation pipeline**
   - Quiz requests gather recent articles for a category.
   - `internal/services/llm_service.go` sends a structured prompt to Groq to generate grounded multiple-choice questions.
   - The quiz API returns the generated quiz immediately rather than relying on precomputed quiz caches.

7. **Persistence model**
   - Postgres is the primary data store, accessed through GORM (`pkg/database/postgres.go`).
   - The model layer includes `article`, `category`, `feed`, `quiz`, `subscriber`, `user`, and `user_quiz_result`, which maps directly to the main business entities.
   - The database is the durable source of truth for feeds, scraped content, quiz records, and user-related state.

8. **Cross-cutting auth and request utilities**
   - `pkg/utils/jwt.go`, `password.go`, and `middleware.go` indicate JWT-based auth and protected routes.
   - `helpers.go`, `getarticles.go`, and related utilities support shared request/data handling across modules.
   - This shared package layer keeps auth, hashing, and request middleware out of the feature modules.

9. **Background and scheduled work**
   - The presence of `internal/scheduler/daily_quiz.go` and a worker entrypoint indicates some logic runs outside request/response handling.
   - This likely covers recurring quiz generation or feed maintenance so the API can stay responsive.
   - The architecture therefore has both synchronous API flows and asynchronous/background jobs.

10. **Tooling and external dependencies**
   - External services that materially shape the architecture are PostgreSQL for storage and Groq for LLM quiz generation.
   - RSS parsing depends on feed ingestion libraries, and article extraction depends on scraper logic rather than trusting feed summaries alone.
   - `docs/swagger.yaml/json` and `swaggo` make the API contract part of the repo, which helps keep the HTTP surface explicit.

Main entry points: [`internal/router/router.go`](https://github.com/sharathdoes/daymark/blob/main/internal/router/router.go) (Router), [`internal/modules/quiz/quiz_router.go`](https://github.com/sharathdoes/daymark/blob/main/internal/modules/quiz/quiz_router.go) (Quizzes), [`pkg/database/postgres.go`](https://github.com/sharathdoes/daymark/blob/main/pkg/database/postgres.go) (Postgres), [`internal/modules/feedSource/feed_router.go`](https://github.com/sharathdoes/daymark/blob/main/internal/modules/feedSource/feed_router.go) (Feed sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_api_main["API main<br/>entrypoint<br/>[main.go]"]
  node_cmd_workers_worker["Worker main<br/>entrypoint<br/>[worker.go]"]
  node_cmd_workers_createfeed["Create feed<br/>worker script<br/>[createfeed.js]"]
  node_scheduler_daily_quiz["Daily quiz<br/>scheduler<br/>[daily_quiz.go]"]
end

subgraph group_api["HTTP API"]
  node_internal_router_router["Router<br/>[router.go]"]
  node_docs_swagger["Swagger docs<br/>api contract<br/>[swagger.yaml]"]
end

subgraph group_domains["Domain modules"]
  node_category_module["Categories<br/>feature module"]
  node_feed_module["Feed sources<br/>feature module<br/>[feed_router.go]"]
  node_articles_module["Articles<br/>feature module<br/>[article_router.go]"]
  node_quiz_module["Quizzes<br/>feature module<br/>[quiz_router.go]"]
  node_user_module["Users<br/>feature module<br/>[user_router.go]"]
  node_subscribe_module["Subscriptions<br/>feature module"]
end

subgraph group_shared["Shared infra"]
  node_rss_service["RSS service<br/>ingestion service<br/>[rss_service.go]"]
  node_scraper_service["Scraper<br/>content extraction<br/>[scraper_service.go]"]
  node_llm_service["LLM service<br/>quiz generation<br/>[llm_service.go]"]
  node_jwt_utils["JWT auth<br/>auth utils<br/>[jwt.go]"]
end

subgraph group_external["External systems"]
  node_postgres_db[("Postgres<br/>database<br/>[postgres.go]")]
  node_groq_api{{"Groq<br/>external llm"}}
end

node_cmd_api_main -->|"bootstraps"| node_internal_router_router
node_internal_router_router -->|"serves"| node_docs_swagger
node_internal_router_router -->|"routes to"| node_category_module
node_internal_router_router -->|"routes to"| node_feed_module
node_internal_router_router -->|"routes to"| node_articles_module
node_internal_router_router -->|"routes to"| node_quiz_module
node_internal_router_router -->|"routes to"| node_user_module
node_internal_router_router -->|"routes to"| node_subscribe_module
node_internal_router_router -->|"protects"| node_jwt_utils
node_feed_module -->|"ingests via"| node_rss_service
node_feed_module -->|"persists"| node_postgres_db
node_rss_service -->|"hands off to"| node_scraper_service
node_scraper_service -->|"feeds"| node_articles_module
node_articles_module -->|"reads/writes"| node_postgres_db
node_quiz_module -->|"generates via"| node_llm_service
node_quiz_module -->|"reads recent"| node_articles_module
node_llm_service -->|"calls"| node_groq_api
node_quiz_module -->|"persists"| node_postgres_db
node_user_module -->|"persists"| node_postgres_db
node_subscribe_module -->|"persists"| node_postgres_db
node_scheduler_daily_quiz -->|"triggers"| node_quiz_module
node_cmd_workers_worker -->|"runs"| node_scheduler_daily_quiz
node_cmd_workers_createfeed -.->|"automation"| node_feed_module

click node_cmd_api_main "https://github.com/sharathdoes/daymark/blob/main/cmd/api/main.go"
click node_cmd_workers_worker "https://github.com/sharathdoes/daymark/blob/main/cmd/workers/worker.go"
click node_cmd_workers_createfeed "https://github.com/sharathdoes/daymark/blob/main/cmd/workers/createfeed.js"
click node_internal_router_router "https://github.com/sharathdoes/daymark/blob/main/internal/router/router.go"
click node_docs_swagger "https://github.com/sharathdoes/daymark/blob/main/docs/swagger.yaml"
click node_category_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/category/catergory_router.go"
click node_feed_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/feedSource/feed_router.go"
click node_articles_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/articles/article_router.go"
click node_quiz_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/quiz/quiz_router.go"
click node_user_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/user/user_router.go"
click node_subscribe_module "https://github.com/sharathdoes/daymark/blob/main/internal/modules/subscribe/subscribe_router.go"
click node_rss_service "https://github.com/sharathdoes/daymark/blob/main/internal/services/rss_service.go"
click node_scraper_service "https://github.com/sharathdoes/daymark/blob/main/internal/services/scraper_service.go"
click node_llm_service "https://github.com/sharathdoes/daymark/blob/main/internal/services/llm_service.go"
click node_scheduler_daily_quiz "https://github.com/sharathdoes/daymark/blob/main/internal/scheduler/daily_quiz.go"
click node_postgres_db "https://github.com/sharathdoes/daymark/blob/main/pkg/database/postgres.go"
click node_jwt_utils "https://github.com/sharathdoes/daymark/blob/main/pkg/utils/jwt.go"

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_cmd_api_main,node_cmd_workers_worker,node_cmd_workers_createfeed,node_scheduler_daily_quiz toneBlue
class node_internal_router_router,node_docs_swagger toneAmber
class node_category_module,node_feed_module,node_articles_module,node_quiz_module,node_user_module,node_subscribe_module toneMint
class node_rss_service,node_scraper_service,node_llm_service,node_jwt_utils toneRose
class node_postgres_db,node_groq_api toneIndigo
```

## Components

### Runtime

Executable entrypoints and scheduled/background work

- [API main](https://github.com/sharathdoes/daymark/blob/main/cmd/api/main.go): entrypoint · Starts the Gin HTTP API process · `cmd/api/main.go`
- [Worker main](https://github.com/sharathdoes/daymark/blob/main/cmd/workers/worker.go): entrypoint · Background worker process · `cmd/workers/worker.go`
- [Create feed](https://github.com/sharathdoes/daymark/blob/main/cmd/workers/createfeed.js): worker script · Auxiliary automation script · `cmd/workers/createfeed.js`
- [Daily quiz](https://github.com/sharathdoes/daymark/blob/main/internal/scheduler/daily_quiz.go): scheduler · Scheduled quiz-related background job · `internal/scheduler/daily_quiz.go`

### HTTP API

Request routing and domain handlers

- [Router](https://github.com/sharathdoes/daymark/blob/main/internal/router/router.go): http router · Wires API routes and middleware · `internal/router/router.go`
- [Swagger docs](https://github.com/sharathdoes/daymark/blob/main/docs/swagger.yaml): api contract · Generated OpenAPI documentation · `docs/swagger.yaml`

### Domain modules

Feature areas with service/repository boundaries

- [Categories](https://github.com/sharathdoes/daymark/blob/main/internal/modules/category/catergory_router.go): feature module · Category CRUD and grouping of feed sources · `internal/modules/category/catergory_router.go`
- [Feed sources](https://github.com/sharathdoes/daymark/blob/main/internal/modules/feedSource/feed_router.go): feature module · RSS feed source management · `internal/modules/feedSource/feed_router.go`
- [Articles](https://github.com/sharathdoes/daymark/blob/main/internal/modules/articles/article_router.go): feature module · Article ingestion and retrieval · `internal/modules/articles/article_router.go`
- [Quizzes](https://github.com/sharathdoes/daymark/blob/main/internal/modules/quiz/quiz_router.go): feature module · Quiz generation and quiz result flows · `internal/modules/quiz/quiz_router.go`
- [Users](https://github.com/sharathdoes/daymark/blob/main/internal/modules/user/user_router.go): feature module · User identity and account flows · `internal/modules/user/user_router.go`
- [Subscriptions](https://github.com/sharathdoes/daymark/blob/main/internal/modules/subscribe/subscribe_router.go): feature module · Subscription-related user flows · `internal/modules/subscribe/subscribe_router.go`

### Shared infra

Cross-cutting services, utilities, and persistence

- [RSS service](https://github.com/sharathdoes/daymark/blob/main/internal/services/rss_service.go): ingestion service · Fetches and parses RSS feeds · `internal/services/rss_service.go`
- [Scraper](https://github.com/sharathdoes/daymark/blob/main/internal/services/scraper_service.go): content extraction · Fetches and cleans full article pages · `internal/services/scraper_service.go`
- [LLM service](https://github.com/sharathdoes/daymark/blob/main/internal/services/llm_service.go): quiz generation · Builds prompts and calls Groq for questions · `internal/services/llm_service.go`
- [JWT auth](https://github.com/sharathdoes/daymark/blob/main/pkg/utils/jwt.go): auth utils · Token auth and protected-route middleware · `pkg/utils/jwt.go`

### External systems

Third-party services and durable stores

- [Postgres](https://github.com/sharathdoes/daymark/blob/main/pkg/database/postgres.go): database · Primary durable store via GORM · `pkg/database/postgres.go`
- **Groq**: external llm · Generates quiz questions from recent articles

## Connections

- API main → Router: bootstraps · Starts the HTTP server and mounts routes
- Router → Swagger docs: serves · Exposes generated API documentation
- Router → Categories: routes to · Dispatches category requests
- Router → Feed sources: routes to · Dispatches feed source requests
- Router → Articles: routes to · Dispatches article requests
- Router → Quizzes: routes to · Dispatches quiz requests
- Router → Users: routes to · Dispatches user requests
- Router → Subscriptions: routes to · Dispatches subscription requests
- Router → JWT auth: protects · Applies auth middleware to guarded routes
- Feed sources → RSS service: ingests via · Fetches and parses feed content
- Feed sources → Postgres: persists · Stores feed source records
- RSS service → Scraper: hands off to · Parsed items may be expanded into full articles
- Scraper → Articles: feeds · Supplies cleaned article content for storage
- Articles → Postgres: reads/writes · Stores and retrieves articles
- Quizzes → LLM service: generates via · Creates quizzes from recent articles
- Quizzes → Articles: reads recent · Pulls article context for quiz generation
- LLM service → Groq: calls · Sends structured prompts to Groq
- Quizzes → Postgres: persists · Stores quiz records and results
- Users → Postgres: persists · Stores user data
- Subscriptions → Postgres: persists · Stores subscriber state
- Daily quiz → Quizzes: triggers · Runs recurring quiz-related jobs
- Worker main → Daily quiz: runs · Worker process executes scheduled background logic
- Create feed → Feed sources: automation · Auxiliary feed-creation workflow
