# flaggigbo/llms-txt-ogechukwu-flagg-igbo architecture

> Architecture diagram of the GitHub repository flaggigbo/llms-txt-ogechukwu-flagg-igbo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo
- Repository: https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo

## Overview

This is an llms.txt directory: users search and browse generated entries or submit a website, which is queued for scraping, generation, validation, and storage before the API serves its files. A separate cadence service checks for site changes and schedules refreshes. The graph includes the major README capabilities and sampled runtime modules; some subsystem links are documented rather than visible in excerpts, so those are dashed where needed.

Main entry points: [`apps/worker/src/consumers/generateConsumer.ts`](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/consumers/generateConsumer.ts) (Generation consumer), [`packages/database/index.ts`](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/database/index.ts) (PostgreSQL database), [`apps/web/src/App.tsx`](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/App.tsx) (Tabbed application), [`apps/api/src/routes/entries.ts`](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/routes/entries.ts) (Entry endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Directory web app"]
  node_webapp["Tabbed application<br/>[App.tsx]"]
  node_home["Search and browse<br/>[HomePage.tsx]"]
  node_searchbar["Search input<br/>[SearchBar.tsx]"]
  node_directory["Directory table<br/>[DirectoryTable.tsx]"]
  node_pagination["Pagination controls"]
  node_addpage["Add entry page<br/>[AddEntryPage.tsx]"]
  node_submission["Submission form<br/>[SubmissionForm.tsx]"]
  node_updates["Updates page<br/>[UpdatesPage.tsx]"]
  node_entrieshook["Entry API hook<br/>[useEntries.ts]"]
end

subgraph group_api["HTTP API"]
  node_api["HTTP gateway<br/>[index.ts]"]
  node_entryroutes["Entry endpoints<br/>[entries.ts]"]
  node_searchroute["Search endpoint<br/>[search.ts]"]
  node_searchservice["Search service<br/>[searchService.ts]"]
  node_urlcheck["Public URL validation<br/>[urlValidator.ts]"]
  node_apistorage["File serving<br/>[storageService.ts]"]
end

subgraph group_processing["Generation pipeline"]
  node_worker["Generation consumer"]
  node_scraper["Website scraper<br/>[scraper.ts]"]
  node_generator["LLM file generator<br/>[llmsGenerator.ts]"]
  node_validator["Standard validator<br/>[llmsValidator.ts]"]
  node_upload["Generated file upload<br/>[storageUpload.ts]"]
end

subgraph group_operations["Scheduling and queue"]
  node_cron["Cadence updater<br/>[checkStaleSites.ts]"]
  node_queue["Generation queue<br/>[index.ts]"]
end

subgraph group_shared["Persistence and storage"]
  node_db[("PostgreSQL database<br/>[index.ts]")]
  node_queries["SQL query definitions<br/>[queries.ts]"]
end

node_visitor(("Directory visitor"))
node_objectstore[("R2 or MinIO")]
node_gemini(("Google Gemini"))
node_websites(("Submitted websites"))

node_visitor -->|"uses"| node_webapp
node_webapp -->|"shows"| node_home
node_webapp -->|"shows"| node_addpage
node_webapp -->|"shows"| node_updates
node_webapp -->|"loads entries"| node_entrieshook
node_home -->|"renders"| node_searchbar
node_home -->|"renders"| node_directory
node_home -->|"renders"| node_pagination
node_addpage -->|"renders"| node_submission
node_updates -->|"renders"| node_directory
node_entrieshook -->|"fetches entries"| node_api
node_api -->|"routes entries"| node_entryroutes
node_api -->|"routes search"| node_searchroute
node_entryroutes -->|"validates submissions"| node_urlcheck
node_entryroutes -->|"reads and writes"| node_db
node_entryroutes -->|"enqueues generation"| node_queue
node_searchroute -->|"delegates search"| node_searchservice
node_searchroute -->|"formats file URLs"| node_entryroutes
node_searchservice -->|"searches entries"| node_db
node_api -->|"serves stored files"| node_apistorage
node_apistorage -.->|"fetches file content"| node_objectstore
node_queue -->|"polls jobs"| node_db
node_worker -->|"processes jobs"| node_queue
node_worker -->|"updates entries"| node_db
node_worker -->|"scrapes site"| node_scraper
node_scraper -.->|"crawls pages"| node_websites
node_worker -->|"generates files"| node_generator
node_generator -.->|"categorizes links"| node_gemini
node_worker -->|"validates output"| node_validator
node_worker -->|"uploads files"| node_upload
node_upload -.->|"writes objects"| node_objectstore
node_cron -->|"claims due sites"| node_db
node_cron -->|"schedules refreshes"| node_queue
node_db -->|"uses SQL builders"| node_queries

click node_webapp "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/App.tsx"
click node_home "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/HomePage.tsx"
click node_searchbar "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/SearchBar.tsx"
click node_directory "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/DirectoryTable.tsx"
click node_pagination "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/PaginationControls.tsx"
click node_addpage "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/AddEntryPage.tsx"
click node_submission "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/SubmissionForm.tsx"
click node_updates "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/UpdatesPage.tsx"
click node_entrieshook "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/hooks/useEntries.ts"
click node_api "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/index.ts"
click node_entryroutes "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/routes/entries.ts"
click node_searchroute "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/routes/search.ts"
click node_searchservice "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/searchService.ts"
click node_urlcheck "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/urlValidator.ts"
click node_apistorage "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/storageService.ts"
click node_worker "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/consumers/generateConsumer.ts"
click node_scraper "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/scraper.ts"
click node_generator "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/llmsGenerator.ts"
click node_validator "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/llmsValidator.ts"
click node_upload "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/storageUpload.ts"
click node_cron "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/cron-updater/src/jobs/checkStaleSites.ts"
click node_queue "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/queue/index.ts"
click node_db "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/database/index.ts"
click node_queries "https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/database/queries.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_webapp,node_home,node_searchbar,node_directory,node_pagination,node_addpage,node_submission,node_updates,node_entrieshook toneBlue
class node_api,node_entryroutes,node_searchroute,node_searchservice,node_urlcheck,node_apistorage,node_objectstore toneAmber
class node_worker,node_scraper,node_generator,node_validator,node_upload toneMint
class node_cron,node_queue toneRose
class node_db,node_queries,node_visitor,node_gemini,node_websites toneIndigo
```

## Components

### Directory web app

- [Tabbed application](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Search and browse](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/HomePage.tsx): `apps/web/src/pages/HomePage.tsx`
- [Search input](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/SearchBar.tsx): `apps/web/src/components/SearchBar.tsx`
- [Directory table](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/DirectoryTable.tsx): `apps/web/src/components/DirectoryTable.tsx`
- [Pagination controls](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/PaginationControls.tsx): `apps/web/src/components/PaginationControls.tsx`
- [Add entry page](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/AddEntryPage.tsx): `apps/web/src/pages/AddEntryPage.tsx`
- [Submission form](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/components/SubmissionForm.tsx): `apps/web/src/components/SubmissionForm.tsx`
- [Updates page](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/pages/UpdatesPage.tsx): `apps/web/src/pages/UpdatesPage.tsx`
- [Entry API hook](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/web/src/hooks/useEntries.ts): `apps/web/src/hooks/useEntries.ts`

### HTTP API

- [HTTP gateway](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Entry endpoints](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/routes/entries.ts): `apps/api/src/routes/entries.ts`
- [Search endpoint](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/routes/search.ts): `apps/api/src/routes/search.ts`
- [Search service](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/searchService.ts): `apps/api/src/services/searchService.ts`
- [Public URL validation](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/urlValidator.ts): `apps/api/src/services/urlValidator.ts`
- [File serving](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/api/src/services/storageService.ts): `apps/api/src/services/storageService.ts`

### Generation pipeline

- [Generation consumer](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/consumers/generateConsumer.ts): `apps/worker/src/consumers/generateConsumer.ts`
- [Website scraper](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/scraper.ts): `apps/worker/src/services/scraper.ts`
- [LLM file generator](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/llmsGenerator.ts): `apps/worker/src/services/llmsGenerator.ts`
- [Standard validator](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/llmsValidator.ts): `apps/worker/src/services/llmsValidator.ts`
- [Generated file upload](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/worker/src/services/storageUpload.ts): `apps/worker/src/services/storageUpload.ts`

### Scheduling and queue

- [Cadence updater](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/apps/cron-updater/src/jobs/checkStaleSites.ts): `apps/cron-updater/src/jobs/checkStaleSites.ts`
- [Generation queue](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/queue/index.ts): `packages/queue/index.ts`

### Persistence and storage

- [PostgreSQL database](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/database/index.ts): `packages/database/index.ts`
- [SQL query definitions](https://github.com/flaggigbo/llms-txt-ogechukwu-flagg-igbo/blob/main/packages/database/queries.ts): `packages/database/queries.ts`

### Other components

- **Directory visitor**
- **R2 or MinIO**
- **Google Gemini**
- **Submitted websites**

## Connections

- Directory visitor → Tabbed application: uses
- Tabbed application → Search and browse: shows (evidence: `apps/web/src/App.tsx`)
- Tabbed application → Add entry page: shows (evidence: `apps/web/src/App.tsx`)
- Tabbed application → Updates page: shows (evidence: `apps/web/src/App.tsx`)
- Tabbed application → Entry API hook: loads entries (evidence: `apps/web/src/App.tsx`)
- Search and browse → Search input: renders (evidence: `apps/web/src/pages/HomePage.tsx`)
- Search and browse → Directory table: renders (evidence: `apps/web/src/pages/HomePage.tsx`)
- Search and browse → Pagination controls: renders (evidence: `apps/web/src/pages/HomePage.tsx`)
- Add entry page → Submission form: renders (evidence: `apps/web/src/pages/AddEntryPage.tsx`)
- Updates page → Directory table: renders (evidence: `apps/web/src/pages/UpdatesPage.tsx`)
- Entry API hook → HTTP gateway: fetches entries (evidence: `apps/web/src/hooks/useEntries.ts`)
- HTTP gateway → Entry endpoints: routes entries (evidence: `apps/api/src/index.ts`)
- HTTP gateway → Search endpoint: routes search (evidence: `apps/api/src/index.ts`)
- Entry endpoints → Public URL validation: validates submissions (evidence: `apps/api/src/routes/entries.ts`)
- Entry endpoints → PostgreSQL database: reads and writes (evidence: `apps/api/src/routes/entries.ts`)
- Entry endpoints → Generation queue: enqueues generation (evidence: `apps/api/src/routes/entries.ts`)
- Search endpoint → Search service: delegates search (evidence: `apps/api/src/routes/search.ts`)
- Search endpoint → Entry endpoints: formats file URLs (evidence: `apps/api/src/routes/search.ts`)
- Search service → PostgreSQL database: searches entries (evidence: `apps/api/src/services/searchService.ts`)
- HTTP gateway → File serving: serves stored files (evidence: `apps/api/src/index.ts`)
- File serving → R2 or MinIO: fetches file content
- Generation queue → PostgreSQL database: polls jobs (evidence: `packages/queue/index.ts`)
- Generation consumer → Generation queue: processes jobs (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- Generation consumer → PostgreSQL database: updates entries (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- Generation consumer → Website scraper: scrapes site (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- Website scraper → Submitted websites: crawls pages
- Generation consumer → LLM file generator: generates files (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- LLM file generator → Google Gemini: categorizes links
- Generation consumer → Standard validator: validates output (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- Generation consumer → Generated file upload: uploads files (evidence: `apps/worker/src/consumers/generateConsumer.ts`)
- Generated file upload → R2 or MinIO: writes objects
- Cadence updater → PostgreSQL database: claims due sites (evidence: `apps/cron-updater/src/jobs/checkStaleSites.ts`)
- Cadence updater → Generation queue: schedules refreshes (evidence: `apps/cron-updater/src/jobs/checkStaleSites.ts`)
- PostgreSQL database → SQL query definitions: uses SQL builders (evidence: `packages/database/index.ts`)
