How cardie-net/frontend works
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: useLearningSession.ts Learning session hook · AuthContext.tsx Auth session state · decks/page.tsx Deck collection · [deckSlug]/page.tsx Deck detail route
Components 21
App shell
- Next.js application
app/layout.tsx - Client providers
components/Providers.tsx - Auth session state
lib/AuthContext.tsx - Global navigation
components/Navbar.tsx - Landing page
app/page.tsx
Deck workspace
- Deck collection
app/decks/page.tsx - Owner deck routes · Username scopes deck ownership.
app/[username]/page.tsx - Deck detail route · Username plus slug identifies a deck.
app/[username]/[deckSlug]/page.tsx - Deck authoring & sharing
components/decks/CreateDeckDialog.tsx - Card authoring & ordering
components/cards/AddCardForm.tsx - Deck data hook
hooks/useDecks.ts - Card data hook
hooks/useCards.ts
Learning modes
- Learning mode routes · Overview, learn, exam, match, and spaced repetition run beneath a deck.
app/[username]/[deckSlug]/learn/page.tsx - Learning session hook · Coordinates progression and answers across modes.
hooks/useLearningSession.ts - Flashcard
components/Flashcard.tsx
Identity & account
- Authentication routes · Login, signup, verification, and password recovery entry points.
app/login/page.tsx - Google sign-in
components/GoogleSignInButton.tsx - Account settings
app/settings/page.tsx
Other components
- External API client · Backend and auth implementation are external to this repository.
lib/api.ts - Domain contracts
types/index.ts - Container delivery
Dockerfile
Connections 23
- 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