# cardie-net/frontend architecture

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

- Interactive diagram: https://gitdiagram.com/cardie-net/frontend
- Repository: https://github.com/cardie-net/frontend

## Overview

#### Purpose and Runtime
This is a Next.js TypeScript flashcard-learning frontend built around user-owned/shareable decks. The README is template-level, but the route and component structure defines product areas for deck authoring, study modes, authentication, and account settings. It runs as a Next.js application, with container build/publish support in `Dockerfile` and `.github/workflows/docker-publish.yml`.

#### Application Shell and Client Providers
The root layout establishes the global application shell and styling in `app/layout.tsx` and `app/globals.css`. Shared application providers are centralized in `components/Providers.tsx`; authentication state is exposed through `lib/AuthContext.tsx`. Global navigation is handled by `components/Navbar.tsx`, making auth/session-aware UI likely cross-cutting.

#### Routing and Deck Identity Boundary
Next.js App Router routes organize both public/discoverable deck pages and authenticated workflows:
- `app/page.tsx` is the landing entry point; `app/decks/page.tsx` is the deck collection/workspace.
- `app/[username]/page.tsx` scopes deck access by owner identity.
- `app/[username]/[deckSlug]/page.tsx` resolves a specific deck by stable URL identity.
This username-plus-slug route boundary is the core resource model used by all learning and deck-detail experiences.

#### Deck Management and Authoring
Deck creation, viewing, sharing, and mutation are represented by `components/decks/CreateDeckDialog.tsx`, `components/decks/DeckActionButtons.tsx`, and `components/decks/ShareDeckDialog.tsx`. Cards are authored and reordered through `components/cards/AddCardForm.tsx` and `components/cards/SortableCardRow.tsx`. `hooks/useDecks.ts` and `hooks/useCards.ts` are the likely state/data orchestration boundary between these UI modules and backend calls.

#### Study Modes and Learning Flow
Each deck branches into dedicated learning experiences beneath `app/[username]/[deckSlug]/`:
- Overview: `overview/page.tsx`
- Standard learning: `learn/page.tsx`
- Exam/testing: `exam/page.tsx`
- Matching game: `match/page.tsx`
- Spaced repetition: `spaced-repetition/page.tsx`

`components/Flashcard.tsx` is the reusable presentation unit for card-based modes. `hooks/useLearningSession.ts` is the key session-state boundary, expected to coordinate card progression, answers, and mode-specific learning state across these routes.

#### Authentication and Account Lifecycle
Authentication has explicit route entry points for login, signup, third-party sign-in, verification, and password recovery: `app/login/page.tsx`, `app/signup/page.tsx`, `app/verify/page.tsx`, `app/forgot-password/page.tsx`, and `app/reset-password/page.tsx`. `components/GoogleSignInButton.tsx` identifies Google as an external identity-provider integration. Account management is isolated in `app/settings/page.tsx` and `app/settings/AccountTab.tsx`.

#### API and Data Contracts
`lib/api.ts` is the central client-side external API boundary; feature hooks should use it rather than embedding transport concerns in route components. Shared domain contracts belong in `types/index.ts`, allowing deck, card, user, and learning-session data to remain consistent across pages, hooks, and UI. The backend itself is not present in this repository, so its API endpoint, persistence layer, and auth provider implementation are external dependencies.

Main entry points: [`hooks/useLearningSession.ts`](https://github.com/cardie-net/frontend/blob/main/hooks/useLearningSession.ts) (Learning session hook), [`lib/AuthContext.tsx`](https://github.com/cardie-net/frontend/blob/main/lib/AuthContext.tsx) (Auth session state), [`app/decks/page.tsx`](https://github.com/cardie-net/frontend/blob/main/app/decks/page.tsx) (Deck collection), [`app/[username]/[deckSlug]/page.tsx`](https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/%5BdeckSlug%5D/page.tsx) (Deck detail route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_next_app["Next.js application<br/>runtime<br/>[layout.tsx]"]
  node_providers["Client providers<br/>provider composition<br/>[Providers.tsx]"]
  node_auth_context["Auth session state<br/>auth context<br/>[AuthContext.tsx]"]
  node_navbar["Global navigation<br/>shared UI<br/>[Navbar.tsx]"]
  node_landing["Landing page<br/>route<br/>[page.tsx]"]
end

subgraph group_decks["Deck workspace"]
  node_deck_collection["Deck collection<br/>workspace route<br/>[page.tsx]"]
  node_owner_decks["Owner deck routes<br/>resource route<br/>[page.tsx]"]
  node_deck_detail["Deck detail route<br/>resource route<br/>[page.tsx]"]
  node_deck_actions["Deck authoring &amp; sharing<br/>deck UI"]
  node_card_authoring["Card authoring &amp; ordering<br/>card UI<br/>[AddCardForm.tsx]"]
  node_deck_data["Deck data hook<br/>data orchestration<br/>[useDecks.ts]"]
  node_card_data["Card data hook<br/>data orchestration<br/>[useCards.ts]"]
end

subgraph group_learning["Learning modes"]
  node_learning_routes["Learning mode routes<br/>route family<br/>[page.tsx]"]
  node_learning_session["Learning session hook<br/>session orchestration"]
  node_flashcard["Flashcard<br/>shared learning UI<br/>[Flashcard.tsx]"]
end

subgraph group_identity["Identity &amp; account"]
  node_auth_routes["Authentication routes<br/>route family<br/>[page.tsx]"]
  node_google_signin["Google sign-in<br/>identity integration UI"]
  node_settings["Account settings<br/>account route<br/>[page.tsx]"]
end

node_api{{"External API client<br/>API boundary<br/>[api.ts]"}}
node_contracts["Domain contracts<br/>shared types<br/>[index.ts]"]
node_container_delivery["Container delivery<br/>build and publish"]

node_next_app -->|"mounts"| node_providers
node_providers -->|"exposes"| node_auth_context
node_next_app -->|"renders"| node_navbar
node_navbar -->|"reads session"| node_auth_context
node_landing -->|"enters"| node_deck_collection
node_deck_collection -->|"browses"| node_owner_decks
node_owner_decks -->|"opens deck"| node_deck_detail
node_deck_detail -->|"selects mode"| node_learning_routes
node_deck_collection -->|"manages decks"| node_deck_actions
node_deck_detail -->|"edits cards"| node_card_authoring
node_deck_actions -->|"uses"| node_deck_data
node_card_authoring -->|"uses"| node_card_data
node_deck_data -->|"calls"| node_api
node_card_data -->|"calls"| node_api
node_learning_routes -->|"runs"| node_learning_session
node_learning_session -->|"drives"| node_flashcard
node_learning_session -->|"loads cards"| node_card_data
node_auth_routes -->|"offers"| node_google_signin
node_auth_routes -->|"establishes session"| node_auth_context
node_settings -->|"uses session"| node_auth_context
node_api -.->|"uses contracts"| node_contracts
node_deck_data -.->|"uses contracts"| node_contracts
node_learning_session -.->|"uses contracts"| node_contracts

click node_next_app "https://github.com/cardie-net/frontend/blob/main/app/layout.tsx"
click node_providers "https://github.com/cardie-net/frontend/blob/main/components/Providers.tsx"
click node_auth_context "https://github.com/cardie-net/frontend/blob/main/lib/AuthContext.tsx"
click node_navbar "https://github.com/cardie-net/frontend/blob/main/components/Navbar.tsx"
click node_landing "https://github.com/cardie-net/frontend/blob/main/app/page.tsx"
click node_deck_collection "https://github.com/cardie-net/frontend/blob/main/app/decks/page.tsx"
click node_owner_decks "https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/page.tsx"
click node_deck_detail "https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/%5BdeckSlug%5D/page.tsx"
click node_deck_actions "https://github.com/cardie-net/frontend/blob/main/components/decks/CreateDeckDialog.tsx"
click node_card_authoring "https://github.com/cardie-net/frontend/blob/main/components/cards/AddCardForm.tsx"
click node_deck_data "https://github.com/cardie-net/frontend/blob/main/hooks/useDecks.ts"
click node_card_data "https://github.com/cardie-net/frontend/blob/main/hooks/useCards.ts"
click node_learning_routes "https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/%5BdeckSlug%5D/learn/page.tsx"
click node_learning_session "https://github.com/cardie-net/frontend/blob/main/hooks/useLearningSession.ts"
click node_flashcard "https://github.com/cardie-net/frontend/blob/main/components/Flashcard.tsx"
click node_auth_routes "https://github.com/cardie-net/frontend/blob/main/app/login/page.tsx"
click node_google_signin "https://github.com/cardie-net/frontend/blob/main/components/GoogleSignInButton.tsx"
click node_settings "https://github.com/cardie-net/frontend/blob/main/app/settings/page.tsx"
click node_api "https://github.com/cardie-net/frontend/blob/main/lib/api.ts"
click node_contracts "https://github.com/cardie-net/frontend/blob/main/types/index.ts"
click node_container_delivery "https://github.com/cardie-net/frontend/blob/main/Dockerfile"

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_next_app,node_providers,node_auth_context,node_navbar,node_landing toneBlue
class node_deck_collection,node_owner_decks,node_deck_detail,node_deck_actions,node_card_authoring,node_deck_data,node_card_data toneAmber
class node_learning_routes,node_learning_session,node_flashcard toneMint
class node_auth_routes,node_google_signin,node_settings toneRose
class node_api,node_contracts,node_container_delivery toneNeutral
```

## Components

### App shell

- [Next.js application](https://github.com/cardie-net/frontend/blob/main/app/layout.tsx): runtime · `app/layout.tsx`
- [Client providers](https://github.com/cardie-net/frontend/blob/main/components/Providers.tsx): provider composition · `components/Providers.tsx`
- [Auth session state](https://github.com/cardie-net/frontend/blob/main/lib/AuthContext.tsx): auth context · `lib/AuthContext.tsx`
- [Global navigation](https://github.com/cardie-net/frontend/blob/main/components/Navbar.tsx): shared UI · `components/Navbar.tsx`
- [Landing page](https://github.com/cardie-net/frontend/blob/main/app/page.tsx): route · `app/page.tsx`

### Deck workspace

- [Deck collection](https://github.com/cardie-net/frontend/blob/main/app/decks/page.tsx): workspace route · `app/decks/page.tsx`
- [Owner deck routes](https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/page.tsx): resource route · Username scopes deck ownership. · `app/[username]/page.tsx`
- [Deck detail route](https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/%5BdeckSlug%5D/page.tsx): resource route · Username plus slug identifies a deck. · `app/[username]/[deckSlug]/page.tsx`
- [Deck authoring & sharing](https://github.com/cardie-net/frontend/blob/main/components/decks/CreateDeckDialog.tsx): deck UI · `components/decks/CreateDeckDialog.tsx`
- [Card authoring & ordering](https://github.com/cardie-net/frontend/blob/main/components/cards/AddCardForm.tsx): card UI · `components/cards/AddCardForm.tsx`
- [Deck data hook](https://github.com/cardie-net/frontend/blob/main/hooks/useDecks.ts): data orchestration · `hooks/useDecks.ts`
- [Card data hook](https://github.com/cardie-net/frontend/blob/main/hooks/useCards.ts): data orchestration · `hooks/useCards.ts`

### Learning modes

- [Learning mode routes](https://github.com/cardie-net/frontend/blob/main/app/%5Busername%5D/%5BdeckSlug%5D/learn/page.tsx): route family · Overview, learn, exam, match, and spaced repetition run beneath a deck. · `app/[username]/[deckSlug]/learn/page.tsx`
- [Learning session hook](https://github.com/cardie-net/frontend/blob/main/hooks/useLearningSession.ts): session orchestration · Coordinates progression and answers across modes. · `hooks/useLearningSession.ts`
- [Flashcard](https://github.com/cardie-net/frontend/blob/main/components/Flashcard.tsx): shared learning UI · `components/Flashcard.tsx`

### Identity & account

- [Authentication routes](https://github.com/cardie-net/frontend/blob/main/app/login/page.tsx): route family · Login, signup, verification, and password recovery entry points. · `app/login/page.tsx`
- [Google sign-in](https://github.com/cardie-net/frontend/blob/main/components/GoogleSignInButton.tsx): identity integration UI · `components/GoogleSignInButton.tsx`
- [Account settings](https://github.com/cardie-net/frontend/blob/main/app/settings/page.tsx): account route · `app/settings/page.tsx`

### Other components

- [External API client](https://github.com/cardie-net/frontend/blob/main/lib/api.ts): API boundary · Backend and auth implementation are external to this repository. · `lib/api.ts`
- [Domain contracts](https://github.com/cardie-net/frontend/blob/main/types/index.ts): shared types · `types/index.ts`
- [Container delivery](https://github.com/cardie-net/frontend/blob/main/Dockerfile): build and publish · `Dockerfile`

## Connections

- Next.js application → Client providers: mounts
- Client providers → Auth session state: exposes
- Next.js application → Global navigation: renders
- Global navigation → Auth session state: reads session
- Landing page → Deck collection: enters
- Deck collection → Owner deck routes: browses
- Owner deck routes → Deck detail route: opens deck
- Deck detail route → Learning mode routes: selects mode
- Deck collection → Deck authoring & sharing: manages decks
- Deck detail route → Card authoring & ordering: edits cards
- Deck authoring & sharing → Deck data hook: uses
- Card authoring & ordering → Card data hook: uses
- Deck data hook → External API client: calls
- Card data hook → External API client: calls
- Learning mode routes → Learning session hook: runs
- Learning session hook → Flashcard: drives
- Learning session hook → Card data hook: loads cards
- Authentication routes → Google sign-in: offers
- Authentication routes → Auth session state: establishes session
- Account settings → Auth session state: uses session
- External API client → Domain contracts: uses contracts
- Deck data hook → Domain contracts: uses contracts
- Learning session hook → Domain contracts: uses contracts