# ibrahimmurtaza/brieflyy architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimmurtaza/brieflyy
- Repository: https://github.com/ibrahimmurtaza/brieflyy

## Overview

Brieflyy is a topic-personalized news briefing SaaS: users sign in, choose topics and delivery preferences, then receive clustered, summarized content in an in-app feed and scheduled email briefs. The graph preserves the main ingest-to-brief stages and the documented Discover, trends, archive, feedback, and account capabilities. Evidence is limited to the README and indexed/read excerpts; unsampled subsystem links are omitted where no caller relationship is shown.

Main entry points: [`src/app.ts`](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/app.ts) (App routes), [`src/pages/routes.ts`](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/pages/routes.ts) (Brief feed), [`src/auth/routes.ts`](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/auth/routes.ts) (Sign-in routes), [`src/ingest/ingest-service.ts`](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/ingest-service.ts) (Feed processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accounts["Accounts &amp; setup"]
  node_authroutes["Sign-in routes<br/>[routes.ts]"]
  node_authservice["Authentication<br/>[auth-service.ts]"]
  node_oauth["Google OAuth<br/>[google-client.ts]"]
  node_onboardingroutes["Setup routes<br/>[routes.ts]"]
  node_onboarding["Topic setup"]
end

subgraph group_content["Content pipeline"]
  node_ingestscheduler["Ingest scheduler"]
  node_registryingest["Registry ingest"]
  node_ingest["Feed processing<br/>[ingest-service.ts]"]
  node_cluster["Cluster formation"]
end

subgraph group_briefs["Briefs &amp; delivery"]
  node_pages["Brief feed<br/>[routes.ts]"]
  node_plans["Brief planning"]
  node_schedulebrief["Scheduled briefs"]
  node_llm["AI summaries"]
  node_email["Email transport<br/>[transport.ts]"]
end

subgraph group_insights["Discovery &amp; insights"]
  node_discover["Recommendations<br/>[routes.ts]"]
  node_trends["Topic trends<br/>[routes.ts]"]
  node_trendsservice["Trend analysis<br/>[trends-service.ts]"]
  node_archive["Archive search"]
  node_feedback["Reader feedback"]
end

subgraph group_platform["HTTP &amp; persistence"]
  node_server["Server bootstrap<br/>[server.ts]"]
  node_app["App routes<br/>[app.ts]"]
  node_db[("SQLite database<br/>[client.ts]")]
  node_topicrepo["Topic repository<br/>[topic-repo.ts]"]
  node_datarepos["Content repositories"]
  node_shell["Shared page shell<br/>[shell.ts]"]
end

node_reader(("Reader"))

node_reader -->|"opens app"| node_server
node_server -->|"creates routes"| node_app
node_app -->|"registers"| node_authroutes
node_reader -->|"signs in"| node_authroutes
node_authroutes -->|"requests auth"| node_authservice
node_authservice -->|"uses provider"| node_oauth
node_authroutes -.->|"continues setup"| node_onboardingroutes
node_onboardingroutes -->|"handles setup"| node_onboarding
node_onboarding -->|"stores topics"| node_topicrepo
node_app -->|"wires scheduler"| node_ingestscheduler
node_ingestscheduler -->|"runs registry"| node_registryingest
node_registryingest -->|"delegates ingest"| node_ingest
node_ingest -->|"persists articles"| node_datarepos
node_ingest -.->|"supplies stories"| node_cluster
node_cluster -.->|"stores clusters"| node_datarepos
node_app -->|"registers pages"| node_pages
node_reader -->|"reads brief"| node_pages
node_pages -->|"loads plan"| node_plans
node_plans -.->|"feeds scheduling"| node_schedulebrief
node_schedulebrief -.->|"requests writing"| node_llm
node_schedulebrief -.->|"delivers brief"| node_email
node_app -->|"registers discovery"| node_discover
node_app -->|"registers trends"| node_trends
node_trends -->|"loads analysis"| node_trendsservice
node_app -->|"wires search"| node_archive
node_pages -->|"searches archive"| node_archive
node_pages -->|"records signals"| node_feedback
node_server -->|"opens database"| node_db
node_topicrepo -->|"queries"| node_db
node_pages -->|"resolves account"| node_shell

click node_server "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/server.ts"
click node_app "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/app.ts"
click node_authroutes "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/auth/routes.ts"
click node_authservice "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/auth/auth-service.ts"
click node_oauth "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/oauth/google-client.ts"
click node_onboardingroutes "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/onboarding/routes.ts"
click node_onboarding "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/onboarding/onboarding-service.ts"
click node_ingestscheduler "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/ingest-scheduler.ts"
click node_registryingest "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/registry-ingest-service.ts"
click node_ingest "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/ingest-service.ts"
click node_cluster "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/cluster-formation-service.ts"
click node_pages "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/pages/routes.ts"
click node_plans "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/brief-plan-service.ts"
click node_schedulebrief "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/scheduled-brief-service.ts"
click node_llm "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/llm-summary-service.ts"
click node_email "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/email/transport.ts"
click node_discover "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/discover/routes.ts"
click node_trends "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/trends/routes.ts"
click node_trendsservice "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/trends-service.ts"
click node_archive "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/archive-search-service.ts"
click node_feedback "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/feedback-service.ts"
click node_db "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/db/client.ts"
click node_topicrepo "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/repos/topic-repo.ts"
click node_datarepos "https://github.com/ibrahimmurtaza/brieflyy/tree/main/src/repos"
click node_shell "https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/pages/shell.ts"

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_authroutes,node_authservice,node_oauth,node_onboardingroutes,node_onboarding toneBlue
class node_ingestscheduler,node_registryingest,node_ingest,node_cluster toneAmber
class node_pages,node_plans,node_schedulebrief,node_llm,node_email toneMint
class node_discover,node_trends,node_trendsservice,node_archive,node_feedback toneRose
class node_server,node_app,node_db,node_topicrepo,node_datarepos,node_shell,node_reader toneIndigo
```

## Components

### Accounts & setup

- [Sign-in routes](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/auth/routes.ts): `src/auth/routes.ts`
- [Authentication](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/auth/auth-service.ts): `src/auth/auth-service.ts`
- [Google OAuth](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/oauth/google-client.ts): `src/oauth/google-client.ts`
- [Setup routes](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/onboarding/routes.ts): `src/onboarding/routes.ts`
- [Topic setup](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/onboarding/onboarding-service.ts): `src/onboarding/onboarding-service.ts`

### Content pipeline

- [Ingest scheduler](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/ingest-scheduler.ts): `src/ingest/ingest-scheduler.ts`
- [Registry ingest](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/registry-ingest-service.ts): `src/ingest/registry-ingest-service.ts`
- [Feed processing](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/ingest/ingest-service.ts): `src/ingest/ingest-service.ts`
- [Cluster formation](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/cluster-formation-service.ts): `src/services/cluster-formation-service.ts`

### Briefs & delivery

- [Brief feed](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/pages/routes.ts): `src/pages/routes.ts`
- [Brief planning](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/brief-plan-service.ts): `src/services/brief-plan-service.ts`
- [Scheduled briefs](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/scheduled-brief-service.ts): `src/services/scheduled-brief-service.ts`
- [AI summaries](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/llm-summary-service.ts): `src/services/llm-summary-service.ts`
- [Email transport](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/email/transport.ts): `src/email/transport.ts`

### Discovery & insights

- [Recommendations](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/discover/routes.ts): `src/discover/routes.ts`
- [Topic trends](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/trends/routes.ts): `src/trends/routes.ts`
- [Trend analysis](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/trends-service.ts): `src/services/trends-service.ts`
- [Archive search](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/archive-search-service.ts): `src/services/archive-search-service.ts`
- [Reader feedback](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/services/feedback-service.ts): `src/services/feedback-service.ts`

### HTTP & persistence

- [Server bootstrap](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/server.ts): `src/server.ts`
- [App routes](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/app.ts): `src/app.ts`
- [SQLite database](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/db/client.ts): `src/db/client.ts`
- [Topic repository](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/repos/topic-repo.ts): `src/repos/topic-repo.ts`
- [Content repositories](https://github.com/ibrahimmurtaza/brieflyy/tree/main/src/repos): `src/repos`
- [Shared page shell](https://github.com/ibrahimmurtaza/brieflyy/blob/main/src/pages/shell.ts): `src/pages/shell.ts`

### Other components

- **Reader**

## Connections

- Reader → Server bootstrap: opens app (evidence: `README.md`)
- Server bootstrap → App routes: creates routes (evidence: `src/server.ts`)
- App routes → Sign-in routes: registers (evidence: `src/app.ts`)
- Reader → Sign-in routes: signs in (evidence: `README.md`)
- Sign-in routes → Authentication: requests auth (evidence: `src/auth/routes.ts`)
- Authentication → Google OAuth: uses provider (evidence: `src/auth/auth-service.ts`)
- Sign-in routes → Setup routes: continues setup
- Setup routes → Topic setup: handles setup (evidence: `src/onboarding/routes.ts`)
- Topic setup → Topic repository: stores topics (evidence: `src/onboarding/onboarding-service.ts`)
- App routes → Ingest scheduler: wires scheduler (evidence: `src/app.ts`)
- Ingest scheduler → Registry ingest: runs registry
- Registry ingest → Feed processing: delegates ingest (evidence: `src/ingest/registry-ingest-service.ts`)
- Feed processing → Content repositories: persists articles (evidence: `src/ingest/ingest-service.ts`)
- Feed processing → Cluster formation: supplies stories
- Cluster formation → Content repositories: stores clusters
- App routes → Brief feed: registers pages (evidence: `src/app.ts`)
- Reader → Brief feed: reads brief (evidence: `README.md`)
- Brief feed → Brief planning: loads plan (evidence: `src/pages/routes.ts`)
- Brief planning → Scheduled briefs: feeds scheduling
- Scheduled briefs → AI summaries: requests writing
- Scheduled briefs → Email transport: delivers brief
- App routes → Recommendations: registers discovery (evidence: `src/app.ts`)
- App routes → Topic trends: registers trends (evidence: `src/app.ts`)
- Topic trends → Trend analysis: loads analysis (evidence: `src/trends/routes.ts`)
- App routes → Archive search: wires search (evidence: `src/app.ts`)
- Brief feed → Archive search: searches archive (evidence: `src/pages/routes.ts`)
- Brief feed → Reader feedback: records signals (evidence: `src/pages/routes.ts`)
- Server bootstrap → SQLite database: opens database (evidence: `src/server.ts`)
- Topic repository → SQLite database: queries (evidence: `src/repos/topic-repo.ts`)
- Brief feed → Shared page shell: resolves account (evidence: `src/pages/routes.ts`)
