# fuerst-one/buchstabiene architecture

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

- Interactive diagram: https://gitdiagram.com/fuerst-one/buchstabiene
- Repository: https://github.com/fuerst-one/buchstabiene

## Overview

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: [`src/components/Game/Game.tsx`](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/Game.tsx) (Game Shell), [`src/server/db/db.ts`](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/db/db.ts) (DB Access), [`src/components/Game/SolutionsDecrypter.tsx`](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/SolutionsDecrypter.tsx) (Reveal Flow), [`src/server/api/savedGames.ts`](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/savedGames.ts) (Persistence API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_root["Landing<br/>route page<br/>[page.tsx]"]
  node_app_game_date["Daily Game<br/>route page<br/>[page.tsx]"]
  node_app_game_highscores["Highscores<br/>route page<br/>[page.tsx]"]
  node_app_game_solutions["Solutions<br/>route page<br/>[page.tsx]"]
  node_app_login["Login<br/>route page<br/>[page.tsx]"]
  node_app_signup["Signup<br/>route page<br/>[page.tsx]"]
  node_app_api_auth["Auth Route<br/>route handler<br/>[route.ts]"]
  node_app_api_login["Login API<br/>route handler<br/>[route.ts]"]
end

subgraph group_game["Game UI"]
  node_game_shell["Game Shell<br/>client feature<br/>[Game.tsx]"]
  node_game_input["Word Entry<br/>client feature<br/>[WordInput.tsx]"]
  node_game_progress["Progress UI<br/>client feature<br/>[FoundWords.tsx]"]
  node_game_reveal["Reveal Flow<br/>client feature"]
  node_game_nav["Game Nav<br/>client feature<br/>[GameNavigation.tsx]"]
  node_game_state["Save State<br/>client hook<br/>[useSaveState.ts]"]
end

subgraph group_server["Server API"]
  node_server_game["Game API<br/>domain api<br/>[game.ts]"]
  node_server_persist["Persistence API<br/>domain api<br/>[savedGames.ts]"]
  node_server_scores["Scores API<br/>domain api<br/>[highscores.ts]"]
  node_server_moderation["Moderation API<br/>domain api<br/>[wordVotes.ts]"]
end

subgraph group_data["Data Layer"]
  node_db_schema[("Schema<br/>[schema.ts]")]
  node_db_runtime[("DB Access<br/>database runtime<br/>[db.ts]")]
end

subgraph group_admin["Admin"]
  node_admin_surface["Admin Console<br/>admin page<br/>[page.tsx]"]
end

subgraph group_scripts["Content Scripts"]
  node_scripts_pipeline{{"Content Pipeline<br/>build scripts"}}
end

subgraph group_shared["Shared Core"]
  node_shared_auth["Auth State<br/>shared auth<br/>[auth.ts]"]
  node_shared_lib["Core Lib<br/>shared utils<br/>[utils.ts]"]
  node_shared_ui["UI Kit<br/>design system<br/>[button.tsx]"]
end

node_app_root -->|"entry"| node_app_game_date
node_app_game_date -->|"renders"| node_game_shell
node_app_game_highscores -->|"loads"| node_server_scores
node_app_game_solutions -->|"shows"| node_game_reveal
node_app_login -->|"submits"| node_app_api_login
node_app_signup -->|"auth flow"| node_app_api_auth
node_app_api_auth -->|"uses"| node_shared_auth
node_game_shell -->|"contains"| node_game_input
node_game_shell -->|"contains"| node_game_progress
node_game_shell -->|"contains"| node_game_reveal
node_game_shell -->|"contains"| node_game_nav
node_game_shell -->|"persists"| node_game_state
node_game_reveal -->|"encrypts"| node_shared_lib
node_game_state -->|"syncs"| node_server_persist
node_server_game -->|"reads"| node_db_runtime
node_server_persist -->|"stores"| node_db_runtime
node_server_scores -->|"stores"| node_db_runtime
node_server_moderation -->|"updates"| node_db_runtime
node_db_runtime -->|"implements"| node_db_schema
node_admin_surface -->|"manages"| node_server_moderation
node_scripts_pipeline -->|"imports"| node_db_runtime
node_scripts_pipeline -->|"applies"| node_server_moderation
node_shared_auth -->|"session aware"| node_server_persist
node_shared_lib -->|"supports"| node_game_shell
node_shared_ui -->|"builds"| node_game_shell
node_shared_ui -->|"builds"| node_admin_surface

click node_app_root "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/page.tsx"
click node_app_game_date "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/page.tsx"
click node_app_game_highscores "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/highscores/page.tsx"
click node_app_game_solutions "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/loesungen/page.tsx"
click node_app_login "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/login/page.tsx"
click node_app_signup "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/signup/page.tsx"
click node_app_api_auth "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_app_api_login "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/api/login/route.ts"
click node_game_shell "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/Game.tsx"
click node_game_input "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/WordInput.tsx"
click node_game_progress "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/FoundWords.tsx"
click node_game_reveal "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/SolutionsDecrypter.tsx"
click node_game_nav "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/GameNavigation.tsx"
click node_game_state "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/useSaveState.ts"
click node_admin_surface "https://github.com/fuerst-one/buchstabiene/blob/main/src/app/admin/page.tsx"
click node_server_game "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/game.ts"
click node_server_persist "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/savedGames.ts"
click node_server_scores "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/highscores.ts"
click node_server_moderation "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/wordVotes.ts"
click node_db_schema "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/db/schema.ts"
click node_db_runtime "https://github.com/fuerst-one/buchstabiene/blob/main/src/server/db/db.ts"
click node_scripts_pipeline "https://github.com/fuerst-one/buchstabiene/blob/main/scripts/updateGamesFromDbAmendments.ts"
click node_shared_auth "https://github.com/fuerst-one/buchstabiene/blob/main/src/auth.ts"
click node_shared_lib "https://github.com/fuerst-one/buchstabiene/blob/main/src/lib/utils.ts"
click node_shared_ui "https://github.com/fuerst-one/buchstabiene/blob/main/src/components/ui/button.tsx"

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_root,node_app_game_date,node_app_game_highscores,node_app_game_solutions,node_app_login,node_app_signup,node_app_api_auth,node_app_api_login,node_shared_auth,node_shared_lib,node_shared_ui toneBlue
class node_game_shell,node_game_input,node_game_progress,node_game_reveal,node_game_nav,node_game_state toneAmber
class node_server_game,node_server_persist,node_server_scores,node_server_moderation toneMint
class node_db_schema,node_db_runtime toneRose
class node_admin_surface toneIndigo
class node_scripts_pipeline toneTeal
```

## Components

### App Router

Public pages, route handlers, and route shells

- [Landing](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/page.tsx): route page · Root landing page for the app · `src/app/page.tsx`
- [Daily Game](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/page.tsx): route page · Main dated gameplay route · `src/app/spielen/[date]/page.tsx`
- [Highscores](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/highscores/page.tsx): route page · Public highscores subpage for a game date · `src/app/spielen/[date]/highscores/page.tsx`
- [Solutions](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/spielen/[date]/loesungen/page.tsx): route page · Public solutions subpage for a game date · `src/app/spielen/[date]/loesungen/page.tsx`
- [Login](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/login/page.tsx): route page · User login entry point · `src/app/login/page.tsx`
- [Signup](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/signup/page.tsx): route page · User registration entry point · `src/app/signup/page.tsx`
- [Auth Route](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/api/auth/[...nextauth]/route.ts): route handler · NextAuth handler mounted under API auth · `src/app/api/auth/[...nextauth]/route.ts`
- [Login API](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/api/login/route.ts): route handler · Custom login route handler · `src/app/api/login/route.ts`

### Game UI

Interactive daily word-game client experience

- [Game Shell](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/Game.tsx): client feature · Main interactive game UI and orchestration · `src/components/Game/Game.tsx`
- [Word Entry](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/WordInput.tsx): client feature · Word input and suggestion flow · `src/components/Game/WordInput.tsx`
- [Progress UI](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/FoundWords.tsx): client feature · Found words and stage/progress display · `src/components/Game/FoundWords.tsx`
- [Reveal Flow](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/SolutionsDecrypter.tsx): client feature · Encrypted solutions and completion dialogs · `src/components/Game/SolutionsDecrypter.tsx`
- [Game Nav](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/GameNavigation.tsx): client feature · Navigation, highscores, and solutions links inside game flows · `src/components/Game/GameNavigation.tsx`
- [Save State](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/Game/useSaveState.ts): client hook · Client-side state persistence and sync · `src/components/Game/useSaveState.ts`

### Server API

Domain logic and persistence-facing handlers

- [Game API](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/game.ts): domain api · Server-side game assembly and rules data · `src/server/api/game.ts`
- [Persistence API](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/savedGames.ts): domain api · Saved games and session-aware restore logic · `src/server/api/savedGames.ts`
- [Scores API](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/highscores.ts): domain api · Highscore recording and retrieval · `src/server/api/highscores.ts`
- [Moderation API](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/api/wordVotes.ts): domain api · Word votes and dictionary amendment workflows · `src/server/api/wordVotes.ts`

### Data Layer

Database schema, migrations, and runtime DB entrypoints

- [Schema](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/db/schema.ts): db schema · Drizzle database schema definition · `src/server/db/schema.ts`
- [DB Access](https://github.com/fuerst-one/buchstabiene/blob/main/src/server/db/db.ts): database runtime · Runtime database entrypoint · `src/server/db/db.ts`

### Admin

Operational review and moderation surface

- [Admin Console](https://github.com/fuerst-one/buchstabiene/blob/main/src/app/admin/page.tsx): admin page · Dictionary, amendments, and votes management · `src/app/admin/page.tsx`

### Content Scripts

Offline generation and maintenance pipeline

- [Content Pipeline](https://github.com/fuerst-one/buchstabiene/blob/main/scripts/updateGamesFromDbAmendments.ts): build scripts · Game generation and amendment maintenance scripts · `scripts/updateGamesFromDbAmendments.ts`

### Shared Core

Cross-cutting utilities, auth state, and UI primitives

- [Auth State](https://github.com/fuerst-one/buchstabiene/blob/main/src/auth.ts): shared auth · Server and client auth helpers and session state · `src/auth.ts`
- [Core Lib](https://github.com/fuerst-one/buchstabiene/blob/main/src/lib/utils.ts): shared utils · Cross-cutting helpers for encryption, dates, validation, and utilities · `src/lib/utils.ts`
- [UI Kit](https://github.com/fuerst-one/buchstabiene/blob/main/src/components/ui/button.tsx): design system · Shared component primitives used across pages and game UI · `src/components/ui/button.tsx`

## Connections

- 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
