How fuerst-one/buchstabiene works
1. This repository is a Next.js App Router application built around a daily word-game domain. The app is not split into a separate frontend/backend deployment; instead, UI routes, server route handlers, database access, and auth all live in the same codebase.
2. The public-facing routes are organized under src/app. The main game entry is src/app/spielen/[date], with dedicated subpages for highscores and loesungen. There are also top-level login, signup, and admin areas, plus a root landing page.
3. The core gameplay subsystem lives in src/components/Game. It contains the interactive game UI (Game.tsx), word entry and suggestion components, found-word tracking, stage/progress display, completion/winner dialogs, navigation, highscores, and a solutions view. This is the main client-side experience engineers would diagram as the interactive front end.
4. There is a notable encrypted-solutions boundary in the game flow. Files like encryptSolutions.ts, SolutionsDecrypter.tsx, and DialogCompleted/DialogWinner suggest the solution set is stored or transmitted in encrypted form and only revealed through client-side decryption logic when appropriate.
5. State persistence for player progress is handled through game-specific hooks and server APIs. useSaveState.ts in the game components points to local/client state synchronization, while src/server/api/savedGames.ts and src/server/api/session.ts indicate server-side persistence and session-aware restore behavior.
6. Authentication is a first-class subsystem. src/app/api/auth/[...nextauth]/route.ts wires in NextAuth, src/app/api/login/route.ts supports a custom login path, and src/auth.ts plus src/zustand/useClientAuth.ts / useServerAuth.ts split auth state between server and client. The login and signup pages in src/app/login and src/app/signup are the user entry points.
7. The server-side application logic is concentrated under src/server/api. Separate modules exist for game, highscores, savedGames, session, wordVotes, and dictionaryAmendments. That structure indicates a thin API layer over domain-specific operations rather than a generic REST backend.
8. Persistence is driven by Drizzle ORM. src/server/db/db.ts and src/server/db/schema.ts define the database boundary, while drizzle.config.ts and drizzle/migrate.ts support schema management and migrations. src/db.ts is a top-level DB entry point, and src/env.ts likely centralizes required runtime configuration.
9. The admin area is a separate operational surface for content and moderation. src/app/admin includes components for amendment lists, the dictionary, and word votes, implying review workflows for curated words and player feedback that affect future game content.
10. There is an offline content-generation pipeline in scripts/. The source word lists in scripts/data/words.txt and removedWords.txt feed utilities that generate letter sets, games, insert/remove games, filter game content, and apply amendments. scripts/updateGamesFromDbAmendments.ts ties the maintenance scripts back to database-managed amendments.
11. Shared infrastructure lives in src/lib, src/config.ts, src/dayjs.ts, and src/zod/auth.ts. These provide cross-cutting helpers such as validation, date formatting, encryption, string/array utilities, and fetch/form helpers, reducing duplication across the app and server modules.
12. The UI system uses shared components under src/components/ui, with components.json and the Tailwind/PostCSS setup indicating a component-library style design system. Layout components in src/components/Layout provide the authenticated shell and logout behavior around the app.
13. From an architecture-diagram perspective, the key flow is: user enters the game route → server-rendered page and API modules load game/session data → client game components manage input, progress, and reveal logic → server APIs persist state and record scores/votes → admin tools and scripts curate dictionary/game content → Drizzle-backed storage remains the system of record.
Main entry points: Game.tsx Game Shell · db.ts DB Access · SolutionsDecrypter.tsx Reveal Flow · savedGames.ts Persistence API
Components 25
App Router
Public pages, route handlers, and route shells
- Landing · Root landing page for the app
src/app/page.tsx - Daily Game · Main dated gameplay route
src/app/spielen/[date]/page.tsx - Highscores · Public highscores subpage for a game date
src/app/spielen/[date]/highscores/page.tsx - Solutions · Public solutions subpage for a game date
src/app/spielen/[date]/loesungen/page.tsx - Login · User login entry point
src/app/login/page.tsx - Signup · User registration entry point
src/app/signup/page.tsx - Auth Route · NextAuth handler mounted under API auth
src/app/api/auth/[...nextauth]/route.ts - Login API · Custom login route handler
src/app/api/login/route.ts
Game UI
Interactive daily word-game client experience
- Game Shell · Main interactive game UI and orchestration
src/components/Game/Game.tsx - Word Entry · Word input and suggestion flow
src/components/Game/WordInput.tsx - Progress UI · Found words and stage/progress display
src/components/Game/FoundWords.tsx - Reveal Flow · Encrypted solutions and completion dialogs
src/components/Game/SolutionsDecrypter.tsx - Game Nav · Navigation, highscores, and solutions links inside game flows
src/components/Game/GameNavigation.tsx - Save State · Client-side state persistence and sync
src/components/Game/useSaveState.ts
Server API
Domain logic and persistence-facing handlers
- Game API · Server-side game assembly and rules data
src/server/api/game.ts - Persistence API · Saved games and session-aware restore logic
src/server/api/savedGames.ts - Scores API · Highscore recording and retrieval
src/server/api/highscores.ts - Moderation API · Word votes and dictionary amendment workflows
src/server/api/wordVotes.ts
Data Layer
Database schema, migrations, and runtime DB entrypoints
Admin
Operational review and moderation surface
- Admin Console · Dictionary, amendments, and votes management
src/app/admin/page.tsx
Content Scripts
Offline generation and maintenance pipeline
- Content Pipeline · Game generation and amendment maintenance scripts
scripts/updateGamesFromDbAmendments.ts
Shared Core
Cross-cutting utilities, auth state, and UI primitives
- Auth State · Server and client auth helpers and session state
src/auth.ts - Core Lib · Cross-cutting helpers for encryption, dates, validation, and utilities
src/lib/utils.ts - UI Kit · Shared component primitives used across pages and game UI
src/components/ui/button.tsx
Connections 26
- Landing → Daily Game: entry · Landing routes users into the daily game
- Daily Game → Game Shell: renders · Server-rendered page mounts the interactive game shell
- Highscores → Scores API: loads · Highscores page depends on score retrieval
- Solutions → Reveal Flow: shows · Solutions route reuses solution reveal experience
- Login → Login API: submits · Login page posts to custom login handler
- Signup → Auth Route: auth flow · Signup/login surface connects to NextAuth auth flow
- Auth Route → Auth State: uses · Auth handler is wired through shared auth configuration
- Game Shell → Word Entry: contains · Main shell coordinates user input and guesses
- Game Shell → Progress UI: contains · Main shell displays progress and found words
- Game Shell → Reveal Flow: contains · Completion and solution reveal logic lives here
- Game Shell → Game Nav: contains · In-game navigation links to highscores and solutions
- Game Shell → Save State: persists · Client gameplay state is synchronized and saved
- Reveal Flow → Core Lib: encrypts · Reveal flow depends on shared encryption helpers
- Save State → Persistence API: syncs · Client state syncs with saved-game endpoints
- Game API → DB Access: reads · Game API reads from database access layer
- Persistence API → DB Access: stores · Saved game and session data are persisted through DB access
- Scores API → DB Access: stores · Highscore data is written and read through DB access
- Moderation API → DB Access: updates · Votes and amendments are stored in the database
- DB Access → Schema: implements · Runtime DB layer is shaped by the schema
- Admin Console → Moderation API: manages · Admin console exposes moderation workflows
- Content Pipeline → DB Access: imports · Maintenance scripts pull amendment data from the database
- Content Pipeline → Moderation API: applies · Scripts reconcile generated games with amendment records
- Auth State → Persistence API: session aware · Server-side restore depends on shared auth/session state
- Core Lib → Game Shell: supports · Shared helpers support client gameplay logic
- UI Kit → Game Shell: builds · UI primitives are used throughout the game interface
- UI Kit → Admin Console: builds · Admin views also use the shared UI kit