# anushkvijay/hldflashcards architecture

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

- Interactive diagram: https://gitdiagram.com/anushkvijay/hldflashcards
- Repository: https://github.com/anushkvijay/hldflashcards

## Overview

FlashSwipe turns an interview-prep URL into swipeable revision cards, then records each learner’s card status. The main flow runs from the web app through the API’s deck routes, scraping, AI generation, and persistence; learners can then browse decks and update progress. The README also describes offline caching and selectable mock, Ollama, and Groq providers. Some frontend and provider wiring is represented using SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`apps/api/src/ai/index.ts`](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/index.ts) (Provider selection), [`apps/api/src/services/deckService.ts`](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/deckService.ts) (Deck workflow), [`apps/api/src/routes/decks.ts`](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/routes/decks.ts) (Deck routes), [`apps/api/src/ai/ollamaProvider.ts`](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/ollamaProvider.ts) (Ollama provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_entry["Web application<br/>[main.tsx]"]
  node_home["Deck home<br/>[HomePage.tsx]"]
  node_deck_view["Swipe deck<br/>[DeckPage.tsx]"]
  node_flash_card["Flashcard display<br/>[FlashCard.tsx]"]
  node_web_api["API client and cache<br/>[api.ts]"]
end

subgraph group_api["API and workflows"]
  node_api_app["Fastify application<br/>[app.ts]"]
  node_deck_routes["Deck routes<br/>[decks.ts]"]
  node_deck_service["Deck workflow<br/>[deckService.ts]"]
  node_scraper["URL scraper<br/>[scraperService.ts]"]
  node_progress["Progress service<br/>[progressService.ts]"]
  node_settings["API configuration<br/>[config.ts]"]
end

subgraph group_generation["Content generation"]
  node_ai_factory["Provider selection<br/>[index.ts]"]
  node_ai_contract["AI provider contract<br/>[provider.ts]"]
  node_prompt["Prompt builder<br/>[promptBuilder.ts]"]
  node_ollama["Ollama provider<br/>[ollamaProvider.ts]"]
  node_groq["Groq provider<br/>[groqProvider.ts]"]
  node_mock["Mock provider<br/>[mockProvider.ts]"]
end

subgraph group_storage["Persistence and contracts"]
  node_contracts["Shared data schemas<br/>[index.ts]"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_database[("SQLite database<br/>[schema.prisma]")]
end

node_learner(("Learner"))
node_source_site(("Study material site"))
node_ollama_service["Ollama service"]
node_groq_service["Groq service"]
node_offline_cache[("Browser offline cache")]

node_learner -->|"uses"| node_web_entry
node_web_entry -->|"renders"| node_home
node_web_entry -->|"renders"| node_deck_view
node_home -->|"requests decks"| node_web_api
node_deck_view -->|"loads and updates"| node_web_api
node_deck_view -->|"renders"| node_flash_card
node_web_api -->|"reads and writes"| node_offline_cache
node_web_api -->|"calls API"| node_deck_routes
node_api_app -->|"registers routes"| node_deck_routes
node_api_app -->|"reads settings"| node_settings
node_deck_routes -->|"handles deck requests"| node_deck_service
node_deck_routes -->|"updates status"| node_progress
node_deck_routes -->|"validates requests"| node_contracts
node_deck_service -->|"scrapes URL"| node_scraper
node_scraper -->|"fetches content"| node_source_site
node_deck_service -->|"creates provider"| node_ai_factory
node_deck_service -->|"persists and reads decks"| node_prisma
node_deck_service -->|"uses shared types"| node_contracts
node_progress -->|"updates card"| node_prisma
node_progress -->|"maps card row"| node_deck_service
node_prisma -.->|"accesses"| node_database
node_ai_factory -->|"selects from config"| node_settings
node_ai_factory -->|"selects provider"| node_mock
node_ai_factory -->|"selects provider"| node_ollama
node_ai_factory -->|"selects provider"| node_groq
node_mock -->|"implements"| node_ai_contract
node_ollama -->|"implements"| node_ai_contract
node_groq -->|"implements"| node_ai_contract
node_ollama -->|"builds prompts"| node_prompt
node_ollama -->|"sends generation request"| node_ollama_service
node_groq -.->|"sends generation request"| node_groq_service
node_ai_factory -.->|"uses shared types"| node_contracts

click node_web_entry "https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/main.tsx"
click node_home "https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/pages/HomePage.tsx"
click node_deck_view "https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/pages/DeckPage.tsx"
click node_flash_card "https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/components/FlashCard.tsx"
click node_web_api "https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/lib/api.ts"
click node_api_app "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/app.ts"
click node_deck_routes "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/routes/decks.ts"
click node_deck_service "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/deckService.ts"
click node_scraper "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/scraperService.ts"
click node_progress "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/progressService.ts"
click node_ai_factory "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/index.ts"
click node_ai_contract "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/provider.ts"
click node_prompt "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/promptBuilder.ts"
click node_ollama "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/ollamaProvider.ts"
click node_groq "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/groqProvider.ts"
click node_mock "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/mockProvider.ts"
click node_settings "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/lib/config.ts"
click node_contracts "https://github.com/anushkvijay/hldflashcards/blob/main/packages/shared/src/index.ts"
click node_prisma "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/lib/prisma.ts"
click node_database "https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/prisma/schema.prisma"

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_web_entry,node_home,node_deck_view,node_flash_card,node_web_api toneBlue
class node_api_app,node_deck_routes,node_deck_service,node_scraper,node_progress,node_settings,node_offline_cache toneAmber
class node_ai_factory,node_ai_contract,node_prompt,node_ollama,node_groq,node_mock toneMint
class node_contracts,node_prisma,node_database toneRose
class node_learner,node_source_site,node_ollama_service,node_groq_service toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Deck home](https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/pages/HomePage.tsx): `apps/web/src/pages/HomePage.tsx`
- [Swipe deck](https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/pages/DeckPage.tsx): `apps/web/src/pages/DeckPage.tsx`
- [Flashcard display](https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/components/FlashCard.tsx): `apps/web/src/components/FlashCard.tsx`
- [API client and cache](https://github.com/anushkvijay/hldflashcards/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API and workflows

- [Fastify application](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Deck routes](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/routes/decks.ts): `apps/api/src/routes/decks.ts`
- [Deck workflow](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/deckService.ts): `apps/api/src/services/deckService.ts`
- [URL scraper](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/scraperService.ts): `apps/api/src/services/scraperService.ts`
- [Progress service](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/services/progressService.ts): `apps/api/src/services/progressService.ts`
- [API configuration](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/lib/config.ts): `apps/api/src/lib/config.ts`

### Content generation

- [Provider selection](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/index.ts): `apps/api/src/ai/index.ts`
- [AI provider contract](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/provider.ts): `apps/api/src/ai/provider.ts`
- [Prompt builder](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/promptBuilder.ts): `apps/api/src/ai/promptBuilder.ts`
- [Ollama provider](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/ollamaProvider.ts): `apps/api/src/ai/ollamaProvider.ts`
- [Groq provider](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/groqProvider.ts): `apps/api/src/ai/groqProvider.ts`
- [Mock provider](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/ai/mockProvider.ts): `apps/api/src/ai/mockProvider.ts`

### Persistence and contracts

- [Shared data schemas](https://github.com/anushkvijay/hldflashcards/blob/main/packages/shared/src/index.ts): `packages/shared/src/index.ts`
- [Prisma client](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`
- [SQLite database](https://github.com/anushkvijay/hldflashcards/blob/main/apps/api/prisma/schema.prisma): `apps/api/prisma/schema.prisma`

### Other components

- **Learner**
- **Study material site**
- **Ollama service**
- **Groq service**
- **Browser offline cache**

## Connections

- Learner → Web application: uses (evidence: `README.md`)
- Web application → Deck home: renders (evidence: `apps/web/src/main.tsx`)
- Web application → Swipe deck: renders (evidence: `apps/web/src/main.tsx`)
- Deck home → API client and cache: requests decks (evidence: `apps/web/src/pages/HomePage.tsx`)
- Swipe deck → API client and cache: loads and updates (evidence: `apps/web/src/pages/DeckPage.tsx`)
- Swipe deck → Flashcard display: renders (evidence: `apps/web/src/pages/DeckPage.tsx`)
- API client and cache → Browser offline cache: reads and writes (evidence: `apps/web/src/lib/api.ts`)
- API client and cache → Deck routes: calls API (evidence: `apps/web/src/lib/api.ts`)
- Fastify application → Deck routes: registers routes (evidence: `apps/api/src/app.ts`)
- Fastify application → API configuration: reads settings (evidence: `apps/api/src/app.ts`)
- Deck routes → Deck workflow: handles deck requests (evidence: `apps/api/src/routes/decks.ts`)
- Deck routes → Progress service: updates status (evidence: `apps/api/src/routes/decks.ts`)
- Deck routes → Shared data schemas: validates requests (evidence: `apps/api/src/routes/decks.ts`)
- Deck workflow → URL scraper: scrapes URL (evidence: `apps/api/src/services/deckService.ts`)
- URL scraper → Study material site: fetches content (evidence: `apps/api/src/services/scraperService.ts`)
- Deck workflow → Provider selection: creates provider (evidence: `apps/api/src/services/deckService.ts`)
- Deck workflow → Prisma client: persists and reads decks (evidence: `apps/api/src/services/deckService.ts`)
- Deck workflow → Shared data schemas: uses shared types (evidence: `apps/api/src/services/deckService.ts`)
- Progress service → Prisma client: updates card (evidence: `apps/api/src/services/progressService.ts`)
- Progress service → Deck workflow: maps card row (evidence: `apps/api/src/services/progressService.ts`)
- Prisma client → SQLite database: accesses
- Provider selection → API configuration: selects from config (evidence: `apps/api/src/ai/index.ts`)
- Provider selection → Mock provider: selects provider (evidence: `apps/api/src/ai/index.ts`)
- Provider selection → Ollama provider: selects provider (evidence: `apps/api/src/ai/index.ts`)
- Provider selection → Groq provider: selects provider (evidence: `apps/api/src/ai/index.ts`)
- Mock provider → AI provider contract: implements (evidence: `apps/api/src/ai/mockProvider.ts`)
- Ollama provider → AI provider contract: implements (evidence: `apps/api/src/ai/ollamaProvider.ts`)
- Groq provider → AI provider contract: implements (evidence: `apps/api/src/ai/groqProvider.ts`)
- Ollama provider → Prompt builder: builds prompts (evidence: `apps/api/src/ai/ollamaProvider.ts`)
- Ollama provider → Ollama service: sends generation request (evidence: `apps/api/src/ai/ollamaProvider.ts`)
- Groq provider → Groq service: sends generation request
- Provider selection → Shared data schemas: uses shared types