# klraaa/kodigo-ai-study-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/klraaa/kodigo-ai-study-buddy
- Repository: https://github.com/klraaa/kodigo-ai-study-buddy

## Overview

Kodigo is a mobile-first, bilingual study app: students provide notes or files, receive AI-generated summaries and cards, then study and review them. The graph covers that creation-to-study workflow as well as the documented auth, community, admin, and offline capabilities. README claims inform several unsampled branches; those links are shown only where the README describes the interaction, while implementation details are omitted.

Main entry points: [`src/app/(app)/sets/[id]/study-page.tsx`](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/sets/%5Bid%5D/study-page.tsx) (Set study), [`src/server/db/client.ts`](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/client.ts) (Postgres), [`src/app/(app)/create/create-flow.tsx`](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/create/create-flow.tsx) (Create flow), [`src/server/actions/auth.ts`](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/auth.ts) (Auth actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and access"]
  node_app["App pages"]
  node_create["Create flow<br/>[create-flow.tsx]"]
  node_parsers["File parsers"]
  node_authui["Auth forms"]
  node_authactions["Auth actions<br/>[auth.ts]"]
end

subgraph group_learning["Study and review"]
  node_study["Set study<br/>[study-page.tsx]"]
  node_flashcards["Flashcards mode<br/>[flashcards.tsx]"]
  node_learn["Learn mode<br/>[learn.tsx]"]
  node_reviewui["Review session<br/>[review-session.tsx]"]
  node_reviewaction["Review action<br/>[reviews.ts]"]
  node_reviewqueries["Review queries<br/>[reviews.ts]"]
  node_srs["SRS scheduler<br/>[srs.ts]"]
end

subgraph group_generation["AI and persistence"]
  node_setactions["Set actions<br/>[sets.ts]"]
  node_ai["AI generation"]
  node_router["AI router<br/>[router.ts]"]
  node_setqueries["Set queries<br/>[sets.ts]"]
  node_db[("Postgres<br/>[client.ts]")]
end

subgraph group_community["Community"]
  node_communityui["Explore and profiles"]
  node_communityactions["Community actions<br/>[community.ts]"]
  node_sharingactions["Sharing actions<br/>[sharing.ts]"]
  node_moderation["Moderation"]
end

subgraph group_platform["Offline platform"]
  node_offline["Offline cache<br/>[offline-cache.ts]"]
  node_serviceworker["Service worker<br/>[sw.js]"]
  node_browserstore[("IndexedDB")]
end

node_student(("Student"))
node_authservice["Neon Auth"]
node_providers["AI providers"]
node_turnstile["Turnstile"]

node_student -->|"provides notes"| node_create
node_create -->|"parses uploads"| node_parsers
node_create -->|"submits content"| node_setactions
node_setactions -->|"requests generation"| node_ai
node_ai -->|"routes models"| node_router
node_router -->|"calls models"| node_providers
node_setactions -->|"stores sets"| node_setqueries
node_setqueries -->|"reads and writes"| node_db
node_student -->|"signs in"| node_authui
node_authui -->|"submits credentials"| node_authactions
node_authactions -->|"authenticates"| node_authservice
node_authactions -->|"checks challenge"| node_turnstile
node_student -->|"opens set"| node_study
node_study -->|"studies cards"| node_flashcards
node_study -->|"practices"| node_learn
node_student -->|"reviews due cards"| node_reviewui
node_reviewui -->|"submits grade"| node_reviewaction
node_learn -->|"records mastery"| node_reviewaction
node_reviewaction -->|"records review"| node_reviewqueries
node_reviewqueries -->|"schedules interval"| node_srs
node_reviewqueries -->|"reads and writes"| node_db
node_student -->|"browses sets"| node_communityui
node_communityui -->|"searches and follows"| node_communityactions
node_communityui -->|"opens shared set"| node_sharingactions
node_sharingactions -->|"screens publication"| node_moderation
node_communityactions -->|"persists activity"| node_db
node_sharingactions -->|"reads and writes"| node_db
node_study -->|"caches opened sets"| node_offline
node_offline -->|"reads and writes"| node_browserstore
node_serviceworker -->|"serves offline app"| node_student

click node_app "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/(app)"
click node_create "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/create/create-flow.tsx"
click node_parsers "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/lib/parsers"
click node_authui "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/auth"
click node_authactions "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/auth.ts"
click node_setactions "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/sets.ts"
click node_ai "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/server/ai"
click node_router "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/ai/router.ts"
click node_setqueries "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/queries/sets.ts"
click node_db "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/client.ts"
click node_study "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/sets/%5Bid%5D/study-page.tsx"
click node_flashcards "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/components/study/flashcards.tsx"
click node_learn "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/components/study/learn.tsx"
click node_reviewui "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/review/session/review-session.tsx"
click node_reviewaction "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/reviews.ts"
click node_reviewqueries "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/queries/reviews.ts"
click node_srs "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/lib/srs.ts"
click node_communityui "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/(app)/explore"
click node_communityactions "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/community.ts"
click node_sharingactions "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/sharing.ts"
click node_moderation "https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/server/moderation"
click node_offline "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/lib/offline-cache.ts"
click node_serviceworker "https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/public/sw.js"

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_app,node_create,node_parsers,node_authui,node_authactions toneBlue
class node_study,node_flashcards,node_learn,node_reviewui,node_reviewaction,node_reviewqueries,node_srs toneAmber
class node_setactions,node_ai,node_router,node_setqueries,node_db toneMint
class node_communityui,node_communityactions,node_sharingactions,node_moderation toneRose
class node_offline,node_serviceworker,node_browserstore,node_student,node_authservice,node_providers,node_turnstile toneIndigo
```

## Components

### App and access

- [App pages](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/(app)): `src/app/(app)`
- [Create flow](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/create/create-flow.tsx): `src/app/(app)/create/create-flow.tsx`
- [File parsers](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/lib/parsers): `src/lib/parsers`
- [Auth forms](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/auth): `src/app/auth`
- [Auth actions](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/auth.ts): `src/server/actions/auth.ts`

### Study and review

- [Set study](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/sets/%5Bid%5D/study-page.tsx): `src/app/(app)/sets/[id]/study-page.tsx`
- [Flashcards mode](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/components/study/flashcards.tsx): `src/components/study/flashcards.tsx`
- [Learn mode](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/components/study/learn.tsx): `src/components/study/learn.tsx`
- [Review session](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/app/(app)/review/session/review-session.tsx): `src/app/(app)/review/session/review-session.tsx`
- [Review action](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/reviews.ts): `src/server/actions/reviews.ts`
- [Review queries](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/queries/reviews.ts): `src/server/db/queries/reviews.ts`
- [SRS scheduler](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/lib/srs.ts): `src/lib/srs.ts`

### AI and persistence

- [Set actions](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/sets.ts): `src/server/actions/sets.ts`
- [AI generation](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/server/ai): `src/server/ai`
- [AI router](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/ai/router.ts): `src/server/ai/router.ts`
- [Set queries](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/queries/sets.ts): `src/server/db/queries/sets.ts`
- [Postgres](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/db/client.ts): `src/server/db/client.ts`

### Community

- [Explore and profiles](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/app/(app)/explore): `src/app/(app)/explore`
- [Community actions](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/community.ts): `src/server/actions/community.ts`
- [Sharing actions](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/server/actions/sharing.ts): `src/server/actions/sharing.ts`
- [Moderation](https://github.com/klraaa/kodigo-ai-study-buddy/tree/main/src/server/moderation): `src/server/moderation`

### Offline platform

- [Offline cache](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/src/lib/offline-cache.ts): `src/lib/offline-cache.ts`
- [Service worker](https://github.com/klraaa/kodigo-ai-study-buddy/blob/main/public/sw.js): `public/sw.js`
- **IndexedDB**

### Other components

- **Student**
- **Neon Auth**
- **AI providers**
- **Turnstile**

## Connections

- Student → Create flow: provides notes
- Create flow → File parsers: parses uploads
- Create flow → Set actions: submits content
- Set actions → AI generation: requests generation
- AI generation → AI router: routes models
- AI router → AI providers: calls models
- Set actions → Set queries: stores sets
- Set queries → Postgres: reads and writes
- Student → Auth forms: signs in
- Auth forms → Auth actions: submits credentials
- Auth actions → Neon Auth: authenticates
- Auth actions → Turnstile: checks challenge
- Student → Set study: opens set
- Set study → Flashcards mode: studies cards
- Set study → Learn mode: practices
- Student → Review session: reviews due cards
- Review session → Review action: submits grade
- Learn mode → Review action: records mastery
- Review action → Review queries: records review
- Review queries → SRS scheduler: schedules interval
- Review queries → Postgres: reads and writes
- Student → Explore and profiles: browses sets
- Explore and profiles → Community actions: searches and follows
- Explore and profiles → Sharing actions: opens shared set
- Sharing actions → Moderation: screens publication
- Community actions → Postgres: persists activity
- Sharing actions → Postgres: reads and writes
- Set study → Offline cache: caches opened sets
- Offline cache → IndexedDB: reads and writes
- Service worker → Student: serves offline app