# bengaudry/studyswipe architecture

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

- Interactive diagram: https://gitdiagram.com/bengaudry/studyswipe
- Repository: https://github.com/bengaudry/studyswipe

## Overview

Studyswipe is a flashcard study application. Its principal workflow is organizing collections and decks, creating or generating cards, then studying a deck. The graph separates collection/deck management, card authoring and study, AI generation, and shared identity/data services. Relationships are limited to calls or imports visible in excerpts or the source index; several page-to-API and subscription details are not sampled, so they are not asserted.

Main entry points: [`src/app/api/generate-flashcards/route.ts`](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/generate-flashcards/route.ts) (Generation endpoint), [`src/lib/session.ts`](https://github.com/bengaudry/studyswipe/blob/master/src/lib/session.ts) (Session service), [`src/lib/prisma.ts`](https://github.com/bengaudry/studyswipe/blob/master/src/lib/prisma.ts) (Application database), [`src/app/(layout)/(authguarded)/collections/page.tsx`](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/(authguarded)/collections/page.tsx) (My collections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Collections and decks"]
  node_collections["My collections<br/>[page.tsx]"]
  node_publiccollections["Public collections<br/>[page.tsx]"]
  node_discover["Discover decks<br/>[page.tsx]"]
  node_collectioncontrols["Collection controls"]
  node_newcollection["New collection"]
  node_decklink["Deck link<br/>[DeckLink.tsx]"]
  node_deckcontrols["Deck controls"]
end

subgraph group_authoring["Card authoring"]
  node_deckpage["Deck editor<br/>[DeckPageBody.tsx]"]
  node_newcard["Card composer<br/>[NewCardModal.tsx]"]
  node_toolselector["Authoring tools<br/>[ToolSelector.tsx]"]
  node_cardpreview["Card preview<br/>[CardPreview.tsx]"]
  node_imageupload["Image upload"]
end

subgraph group_study["Study experience"]
  node_playpage["Study deck page<br/>[page.tsx]"]
  node_playercontext["Study progress<br/>[PlayerContext.tsx]"]
end

subgraph group_generation["AI generation"]
  node_generatehook["Generation client"]
  node_generateapi["Generation endpoint<br/>[route.ts]"]
  node_prompts["Prompt templates"]
  node_schemas["Output schemas<br/>[aiSchemas.ts]"]
  node_models["Model access rules<br/>[aiModels.ts]"]
end

subgraph group_services["Identity and data"]
  node_user(("Account holder"))
  node_authclient["Auth hook<br/>[useAuth.ts]"]
  node_authapi["Auth endpoint<br/>[route.ts]"]
  node_session["Session service<br/>[session.ts]"]
  node_collectionapi["Collection API<br/>[route.ts]"]
  node_deckapi["Deck API<br/>[route.ts]"]
  node_cardapi["Card API<br/>[route.ts]"]
  node_fillapi["Bulk card import<br/>[route.ts]"]
  node_database[("Application database<br/>[prisma.ts]")]
  node_redis[("Usage counter<br/>[redis.ts]")]
  node_subscription["Subscription pages<br/>[page.tsx]"]
  node_stripehook["Stripe webhook<br/>[route.ts]"]
end

node_browser(("Learner"))
node_stripe["Stripe"]

node_browser -->|"opens"| node_collections
node_browser -->|"browses"| node_discover
node_browser -->|"studies"| node_playpage
node_collections -->|"renders"| node_newcollection
node_collections -->|"renders"| node_decklink
node_collections -->|"renders"| node_collectioncontrols
node_collections -->|"renders"| node_deckcontrols
node_decklink -->|"uses"| node_cardpreview
node_newcard -->|"calls"| node_generatehook
node_newcard -->|"renders"| node_toolselector
node_newcard -->|"uses"| node_imageupload
node_generatehook -->|"posts"| node_generateapi
node_generateapi -->|"authenticates"| node_session
node_generateapi -->|"validates output"| node_schemas
node_generateapi -->|"checks access"| node_models
node_generateapi -->|"uses prompts"| node_prompts
node_generateapi -->|"counts usage"| node_redis
node_generateapi -->|"reads and writes"| node_database
node_authclient -->|"fetches session"| node_authapi
node_authapi -->|"checks session"| node_session
node_session -->|"loads user"| node_database
node_collectionapi -->|"authenticates"| node_session
node_collectionapi -->|"reads and writes"| node_database
node_deckapi -->|"authenticates"| node_session
node_deckapi -->|"reads and writes"| node_database
node_cardapi -->|"authenticates"| node_session
node_cardapi -->|"reads and writes"| node_database
node_fillapi -->|"authenticates"| node_session
node_fillapi -->|"reads and writes"| node_database
node_playpage -.->|"provides study state"| node_playercontext
node_user -->|"manages plan"| node_subscription
node_stripehook -->|"updates records"| node_database
node_stripe -.->|"sends events"| node_stripehook

click node_collections "https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/(authguarded)/collections/page.tsx"
click node_publiccollections "https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/collections/%5Busername%5D/page.tsx"
click node_discover "https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/discover/page.tsx"
click node_collectioncontrols "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/CollectionOptionsDropdown.tsx"
click node_newcollection "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/NewCollectionModal.tsx"
click node_decklink "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/DeckLink.tsx"
click node_deckcontrols "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/DeckOptionsDropdown.tsx"
click node_deckpage "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/DeckPageBody.tsx"
click node_newcard "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/NewCardModal.tsx"
click node_toolselector "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/ToolSelector.tsx"
click node_cardpreview "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/CardPreview.tsx"
click node_imageupload "https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useSupabaseImageUpload.tsx"
click node_playpage "https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/play/%5Bdeckid%5D/page.tsx"
click node_playercontext "https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/play/PlayerContext.tsx"
click node_generatehook "https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useAiCardGeneration.ts"
click node_generateapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/generate-flashcards/route.ts"
click node_prompts "https://github.com/bengaudry/studyswipe/blob/master/src/lib/generationPrompts.ts"
click node_schemas "https://github.com/bengaudry/studyswipe/blob/master/src/lib/aiSchemas.ts"
click node_models "https://github.com/bengaudry/studyswipe/blob/master/src/lib/aiModels.ts"
click node_authclient "https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useAuth.ts"
click node_authapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/auth/route.ts"
click node_session "https://github.com/bengaudry/studyswipe/blob/master/src/lib/session.ts"
click node_collectionapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/collection/route.ts"
click node_deckapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/deck/route.ts"
click node_cardapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/card/route.ts"
click node_fillapi "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/fill/route.ts"
click node_database "https://github.com/bengaudry/studyswipe/blob/master/src/lib/prisma.ts"
click node_redis "https://github.com/bengaudry/studyswipe/blob/master/src/lib/redis.ts"
click node_subscription "https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/(authguarded)/subscription/page.tsx"
click node_stripehook "https://github.com/bengaudry/studyswipe/blob/master/src/app/api/webhooks/stripe/route.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_collections,node_publiccollections,node_discover,node_collectioncontrols,node_newcollection,node_decklink,node_deckcontrols toneBlue
class node_deckpage,node_newcard,node_toolselector,node_cardpreview,node_imageupload toneAmber
class node_playpage,node_playercontext toneMint
class node_generatehook,node_generateapi,node_prompts,node_schemas,node_models toneRose
class node_user,node_authclient,node_authapi,node_session,node_collectionapi,node_deckapi,node_cardapi,node_fillapi,node_database,node_redis,node_subscription,node_stripehook,node_browser,node_stripe toneIndigo
```

## Components

### Collections and decks

- [My collections](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/(authguarded)/collections/page.tsx): `src/app/(layout)/(authguarded)/collections/page.tsx`
- [Public collections](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/collections/%5Busername%5D/page.tsx): `src/app/(layout)/collections/[username]/page.tsx`
- [Discover decks](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/discover/page.tsx): `src/app/(layout)/discover/page.tsx`
- [Collection controls](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/CollectionOptionsDropdown.tsx): `src/components/pages/collections/CollectionOptionsDropdown.tsx`
- [New collection](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/NewCollectionModal.tsx): `src/components/pages/collections/NewCollectionModal.tsx`
- [Deck link](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/collections/DeckLink.tsx): `src/components/pages/collections/DeckLink.tsx`
- [Deck controls](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/DeckOptionsDropdown.tsx): `src/components/pages/deck/DeckOptionsDropdown.tsx`

### Card authoring

- [Deck editor](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/DeckPageBody.tsx): `src/components/pages/deck/DeckPageBody.tsx`
- [Card composer](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/NewCardModal.tsx): `src/components/pages/deck/NewCardModal.tsx`
- [Authoring tools](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/ToolSelector.tsx): `src/components/pages/deck/ToolSelector.tsx`
- [Card preview](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/deck/CardPreview.tsx): `src/components/pages/deck/CardPreview.tsx`
- [Image upload](https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useSupabaseImageUpload.tsx): `src/hooks/useSupabaseImageUpload.tsx`

### Study experience

- [Study deck page](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/play/%5Bdeckid%5D/page.tsx): `src/app/(layout)/play/[deckid]/page.tsx`
- [Study progress](https://github.com/bengaudry/studyswipe/blob/master/src/components/pages/play/PlayerContext.tsx): `src/components/pages/play/PlayerContext.tsx`

### AI generation

- [Generation client](https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useAiCardGeneration.ts): `src/hooks/useAiCardGeneration.ts`
- [Generation endpoint](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/generate-flashcards/route.ts): `src/app/api/generate-flashcards/route.ts`
- [Prompt templates](https://github.com/bengaudry/studyswipe/blob/master/src/lib/generationPrompts.ts): `src/lib/generationPrompts.ts`
- [Output schemas](https://github.com/bengaudry/studyswipe/blob/master/src/lib/aiSchemas.ts): `src/lib/aiSchemas.ts`
- [Model access rules](https://github.com/bengaudry/studyswipe/blob/master/src/lib/aiModels.ts): `src/lib/aiModels.ts`

### Identity and data

- **Account holder**
- [Auth hook](https://github.com/bengaudry/studyswipe/blob/master/src/hooks/useAuth.ts): `src/hooks/useAuth.ts`
- [Auth endpoint](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/auth/route.ts): `src/app/api/auth/route.ts`
- [Session service](https://github.com/bengaudry/studyswipe/blob/master/src/lib/session.ts): `src/lib/session.ts`
- [Collection API](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/collection/route.ts): `src/app/api/collection/route.ts`
- [Deck API](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/deck/route.ts): `src/app/api/deck/route.ts`
- [Card API](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/card/route.ts): `src/app/api/card/route.ts`
- [Bulk card import](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/fill/route.ts): `src/app/api/fill/route.ts`
- [Application database](https://github.com/bengaudry/studyswipe/blob/master/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Usage counter](https://github.com/bengaudry/studyswipe/blob/master/src/lib/redis.ts): `src/lib/redis.ts`
- [Subscription pages](https://github.com/bengaudry/studyswipe/blob/master/src/app/(layout)/(authguarded)/subscription/page.tsx): `src/app/(layout)/(authguarded)/subscription/page.tsx`
- [Stripe webhook](https://github.com/bengaudry/studyswipe/blob/master/src/app/api/webhooks/stripe/route.ts): `src/app/api/webhooks/stripe/route.ts`

### Other components

- **Learner**
- **Stripe**

## Connections

- Learner → My collections: opens (evidence: `README.md`)
- Learner → Discover decks: browses (evidence: `README.md`)
- Learner → Study deck page: studies (evidence: `README.md`)
- My collections → New collection: renders (evidence: `src/app/(layout)/(authguarded)/collections/page.tsx`)
- My collections → Deck link: renders (evidence: `src/app/(layout)/(authguarded)/collections/page.tsx`)
- My collections → Collection controls: renders (evidence: `src/app/(layout)/(authguarded)/collections/page.tsx`)
- My collections → Deck controls: renders (evidence: `src/app/(layout)/(authguarded)/collections/page.tsx`)
- Deck link → Card preview: uses (evidence: `src/components/pages/collections/DeckLink.tsx`)
- Card composer → Generation client: calls (evidence: `src/components/pages/deck/NewCardModal.tsx`)
- Card composer → Authoring tools: renders (evidence: `src/components/pages/deck/NewCardModal.tsx`)
- Card composer → Image upload: uses (evidence: `src/components/pages/deck/NewCardModal.tsx`)
- Generation client → Generation endpoint: posts (evidence: `src/hooks/useAiCardGeneration.ts`)
- Generation endpoint → Session service: authenticates (evidence: `src/app/api/generate-flashcards/route.ts`)
- Generation endpoint → Output schemas: validates output (evidence: `src/app/api/generate-flashcards/route.ts`)
- Generation endpoint → Model access rules: checks access (evidence: `src/app/api/generate-flashcards/route.ts`)
- Generation endpoint → Prompt templates: uses prompts (evidence: `src/app/api/generate-flashcards/route.ts`)
- Generation endpoint → Usage counter: counts usage (evidence: `src/app/api/generate-flashcards/route.ts`)
- Generation endpoint → Application database: reads and writes (evidence: `src/app/api/generate-flashcards/route.ts`)
- Auth hook → Auth endpoint: fetches session (evidence: `src/hooks/useAuth.ts`)
- Auth endpoint → Session service: checks session (evidence: `src/app/api/auth/route.ts`)
- Session service → Application database: loads user (evidence: `src/lib/session.ts`)
- Collection API → Session service: authenticates (evidence: `src/app/api/collection/route.ts`)
- Collection API → Application database: reads and writes (evidence: `src/app/api/collection/route.ts`)
- Deck API → Session service: authenticates (evidence: `src/app/api/deck/route.ts`)
- Deck API → Application database: reads and writes (evidence: `src/app/api/deck/route.ts`)
- Card API → Session service: authenticates (evidence: `src/app/api/card/route.ts`)
- Card API → Application database: reads and writes (evidence: `src/app/api/card/route.ts`)
- Bulk card import → Session service: authenticates (evidence: `src/app/api/fill/route.ts`)
- Bulk card import → Application database: reads and writes (evidence: `src/app/api/fill/route.ts`)
- Study deck page → Study progress: provides study state
- Account holder → Subscription pages: manages plan (evidence: `README.md`)
- Stripe webhook → Application database: updates records (evidence: `src/app/api/webhooks/stripe/route.ts`)
- Stripe → Stripe webhook: sends events
