# sudokuru/frontend architecture

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

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

## Overview

##### Project type and purpose
- This is a cross-platform frontend-only application (“Frontend” repo) built with React Native Web & TypeScript.
- It provides a world-class Sudoku UI (play, learn, statistics, drills) that runs in a browser (Web), in Expo (Android), and in a Tauri wrapper (Windows, Linux).

##### File structure
- Top‐level directories:
- `.github/` → CI/CD workflows, composite GitHub Actions (Cloudflare deploy, set changelog).
- `docs/` → design docs, API docs, screenshots.
- `e2e/web/` → Playwright end-to-end tests (components, pages, specs, test data).
- `sudokuru/` → actual application code:
– `app/` → React application:
- `Pages/` (React pages)
- `Components/` (UI components by feature: SudokuBoard, Home, Profile, etc.)
- `Contexts/` (React Contexts for state)
- `Api/` (service layer wrapping AsyncStorage/LocalStorage)
- `Data/` (bundled puzzles TS files)
- `Functions/` (helpers, local DB wrappers, util functions)
- `Navigation/` (DrawerNavigator)
– `src-tauri/` → Rust backend for desktop via Tauri (file `main.rs`, `build.rs`, `Cargo.toml`).
– `public/`, `app.config.ts`, `eas.json` → Expo & static assets.
- Configuration files: `package.json`, `tsconfig.json`, `babel.config.js`, Prettier, ESLint, Playwright config.

##### README insights
- Confirms this is the primary UI module for an open-source Sudoku platform.
- Describes features (play, lessons, stats, hints, drills).
- Explains code structure (app folder breakdown).
- Details supported platforms and testing strategy (Playwright).

##### Main components & their interactions
a. Frontend UI Layer
- Pages (e.g. HomePage, PlayPage, SudokuPage) host Components.
- Components (buttons, boards, modals) consume state via Contexts.
b. State & Services
- Context Providers (InitializeContext, PreferencesContext) manage global state.
- Api layer (app/Api/*.ts) abstracts AsyncStorage/LocalStorage to read/write user preferences, profile, statistics.
c. Data sources
- Bundled puzzles in TS files (app/Data/puzzles).
- LocalDatabase wrapper (Functions/LocalDatabase) for optional more complex storage.
- NPM Sudokuru Clearinghouse library for generating puzzles & hints.
d. Platform runtimes
- Web: React Native Web running in browser.
- Mobile: Expo Go client or standalone APK (Android).
- Desktop: Tauri combining the same web bundle in a WebView with a Rust backend for OS integration.
e. CI/CD & Testing
- GitHub Actions pipeline builds, runs tests, deploys web via Cloudflare composite action.
- Playwright E2E tests (e2e/web) run against the running web instance.

##### Architectural patterns & design principles
- Component‐based (React) with clear separation of pages vs. reusable components.
- State management via React Context (no heavy Redux).
- Service abstraction layer (Api) isolates storage implementation.
- Single codebase targets multiple platforms via React Native Web + Expo + Tauri.

1) User Devices/Environments (Browser, Expo, Desktop)
2) Platform Runtimes (Webpack/static hosting, Expo runtime, Tauri + Rust)
3) UI Layer (Pages, Components, Styling)
4) State/Service Layer (Contexts, Api, Functions)
5) Data Layer (Puzzles files, AsyncStorage/LocalStorage, LocalDatabase, external npm modules)
- Rectangles (blue) for UI components and pages.
- Rectangles (green) for Contexts & service modules.
- UI → Contexts (state reads)
- UI → Api → Storage (reads/writes)
- UI → Data/puzzles (reads)
- Api → Storage (reads/writes)
- UI → npm module (hint/puzzle generation)
- CI/CD → builds & deploys Web bundle to CDN, packages mobile & desktop apps
- Playwright tests → Web instance

##### Essential elements
- Clear labels on each component block (e.g. “PlayPage.tsx”, “PreferencesContext.ts”).
- A boxed grouping for CI/CD outside the runtime, showing pipelines and Playwright.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% User Environments
  subgraph "User Environments"
    direction TB
    Browser["Browser"]:::env
    ExpoApp["Expo App"]:::env
    DesktopApp["Desktop App"]:::env
  end

  %% Platform Runtimes
  subgraph "Platform Runtimes"
    direction TB
    Webpack["Webpack / Static Hosting"]:::runtime
    ExpoRuntime["Expo Runtime"]:::runtime
    subgraph "Tauri Wrapper"
      direction TB
      TauriWebview["WebView Bundle"]:::runtime
      RustBackend["Rust Backend"]:::backend
    end
  end

  %% UI Layer
  subgraph "UI Layer"
    direction TB
    Pages["Pages\n(sudokuru/app/Pages/)"]:::ui
    Components["Components\n(sudokuru/app/Components/)"]:::ui
    Styling["Styling\n(sudokuru/app/Styling/)"]:::ui
  end

  %% State & Service Layer
  subgraph "State & Service Layer"
    direction TB
    Contexts["Contexts\n(sudokuru/app/Contexts/)"]:::service
    Api["API\n(sudokuru/app/Api/)"]:::service
    Functions["Functions\n(Helpers & Wrappers)"]:::service
    AsyncStorage["AsyncStorage Wrapper\n(AsyncStorage.ts)"]:::storage
    LocalDB["LocalDatabase Wrapper\n(LocalDatabase.ts)"]:::storage
    Utils["Utils\n(Utils.ts)"]:::service
    WindowDim["WindowDimensions\n(WindowDimensions.ts)"]:::service
    Lessons["LearnedLessons\n(learnedLessons.ts)"]:::service
    Navigation["Navigation\n(DrawerNavigator.tsx)"]:::service
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    Puzzles["Bundled Puzzles\n(sudokuru/app/Data/puzzles/)"]:::storage
    LocalStorage["LocalStorage"]:::storage
    Clearinghouse["Sudokuru Clearinghouse\n(NPM Module)"]:::external
  end

  %% CI/CD & Testing
  subgraph "CI/CD & Testing"
    direction TB
    CI["GitHub Actions Pipeline"]:::ci
    CF["Cloudflare Deploy Action"]:::ci
    Changelog["Set Changelog Date Action"]:::ci
    Playwright["Playwright E2E Tests\n(e2e/web/)"]:::test
  end

  %% Connections: Environments to Runtimes
  Browser -->|"loads bundle"| Webpack
  ExpoApp -->|"runs on"| ExpoRuntime
  DesktopApp -->|"runs on"| TauriWebview
  TauriWebview -->|"calls"| RustBackend

  %% Runtimes to UI
  Webpack -->|"serves app"| Pages
  ExpoRuntime -->|"renders app"| Pages
  TauriWebview -->|"renders app"| Pages

  %% UI interactions
  Pages -->|"uses components"| Components
  Pages -->|"applies themes"| Styling
  Components -->|"consumes state"| Contexts
  Components -->|"calls navigation"| Navigation

  %% UI to Services
  Components -->|"reads preferences"| Contexts
  Components -->|"fetchPuzzle()"| Puzzles
  Components -->|"generateHint()"| Clearinghouse
  Pages -->|"reads/writes"| Api

  %% Services to Storage
  Api -->|"getPref()/savePref()"| AsyncStorage
  Api -->|"getStats()/saveStats()"| LocalStorage
  Api -->|"advanced storage"| LocalDB
  Contexts -->|"init state via"| Api

  %% CI/CD flows
  CI -->|"build & test"| Webpack
  CI -->|deploy| CF
  CI -->|update| Changelog
  Playwright -->|"tests on"| Webpack

  %% Click Events
  click Pages "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Pages/"
  click Components "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Components/"
  click Contexts "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Contexts/"
  click Api "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Api/"
  click Puzzles "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Data/puzzles/"
  click AsyncStorage "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Functions/AsyncStorage.ts"
  click LocalDB "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Functions/LocalDatabase.ts"
  click Utils "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Functions/Utils.ts"
  click WindowDim "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Functions/WindowDimensions.ts"
  click Lessons "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Functions/learnedLessons.ts"
  click Navigation "https://github.com/sudokuru/frontend/blob/main/sudokuru/app/Navigation/DrawerNavigator.tsx"
  click Styling "https://github.com/sudokuru/frontend/tree/main/sudokuru/app/Styling/"
  click CI "https://github.com/sudokuru/frontend/blob/main/.github/workflows/pipeline.yml"
  click CF "https://github.com/sudokuru/frontend/blob/main/.github/workflows/composite-actions/cloudflare-deployment/action.yml"
  click Changelog "https://github.com/sudokuru/frontend/blob/main/.github/workflows/composite-actions/set-changelog-date/action.yml"
  click Playwright "https://github.com/sudokuru/frontend/tree/main/e2e/web/"

  %% Styles
  classDef env fill:#D5E8D4,stroke:#82B366,stroke-width:2px
  classDef runtime fill:#E1D5E7,stroke:#9673A6,stroke-width:2px
  classDef backend fill:#CCCCCC,stroke:#999999,stroke-width:2px
  classDef ui fill:#DAE8FC,stroke:#6C8EBF,stroke-width:2px
  classDef service fill:#D5E8D4,stroke:#82B366,stroke-width:2px
  classDef storage fill:#F8CECC,stroke:#B85450,stroke-width:2px
  classDef external fill:#FFF2CC,stroke:#D6B656,stroke-width:2px,stroke-dasharray: 5 5
  classDef ci fill:#FFE6CC,stroke:#D79B00,stroke-width:2px
  classDef test fill:#E1F5A9,stroke:#82B366,stroke-width:2px
```
