# viddie/goldberries-frontend architecture

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

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

## Overview

1. **What this repo is**
   - This is the **React frontend** for goldberries.net, a database/archive for Celeste modded map challenge completions.
   - It is a **single-page application** that renders views, forms, dashboards, and viewers on top of a separate backend API.

2. **Top-level architecture**
   - The code is organized around **route-level pages** in `src/pages`, **shared UI components** in `src/components`, **cross-cutting hooks/providers** in `src/hooks`, and **API/data helpers** in `src/util`.
   - `src/index.js` and `src/App.js` are the entry points that wire the app shell, routing, providers, and global styling.

3. **Frontend-to-backend boundary**
   - The main data boundary is `src/util/api.js` plus `src/hooks/useApi.jsx`, which centralize HTTP access to the backend.
   - Most feature pages consume server-provided data for challenges, submissions, campaigns, players, stats, and moderation/admin actions.
   - The frontend does not appear to own the core data model; it is primarily a **presentation and interaction layer** over the API.

4. **Route-level feature areas**
   - `src/pages` splits the app into major domains: **Challenges, Campaigns, Maps, Submissions, Players, Accounts, Search, Stats, Suggestions, Reports, Rules, FAQ, Legal, and Auth/Login**.
   - There is also a significant **admin/moderation area** under `src/pages/manage` for accounts, submissions queue, posts, logs, server settings, file uploads, and traffic analytics.
   - This suggests the app serves both general users and privileged staff workflows.

5. **Core domain subsystems**
   - The repository has dedicated component groups for:
     - **submissions**: submission creation, multi/single submission flows, verification-related UI
     - **likes/wishlist**: community preference and wishlist interactions
     - **recent submissions**: activity feed views
     - **stats_page**: aggregated analytics dashboards
     - **suggestions_page**: proposal creation and review flows
   - These are not generic widgets; they reflect the main product workflows around community moderation and tracking challenge completions.

6. **Map and level visualization**
   - A major subsystem is `src/components/map_data` and `src/components/map_image`, which handle map-related visualization and inspection.
   - The map viewer has a more specialized internal structure with controls, sidebar, entity rendering, and many entity-specific renderers, indicating a **custom visualization pipeline** rather than a simple image display.
   - This likely consumes structured map data from the backend and transforms it into interactive map views and campaign galleries.

7. **Shared UI and domain primitives**
   - `src/components/basic` contains generic UI primitives such as links, buttons, containers, tooltips, loading/error states, and copy/share actions.
   - `src/components/goldberries` contains reusable **domain-specific atoms** like player chips, campaign icons, challenge selectors, difficulty badges, verification status chips, and submission embeds.
   - These components form the shared vocabulary used across pages and forms.

8. **Forms and editor workflows**
   - `src/components/forms` contains structured data-entry flows for domain objects such as **accounts, badges, campaigns, challenges, maps, posts, and submissions**.
   - These are paired with interactive widgets like string-list editors, selects, toggles, and filters, which suggests the frontend is used for **creating and editing backend records**, not only browsing them.
   - Some forms support bulk or derived creation flows, such as creating campaigns from GameBanana or creating full challenges.

9. **Cross-cutting state and app services**
   - `src/hooks` provides reusable app services:
     - `AuthProvider` for authentication/session state
     - `AppSettingsProvider` for user preferences
     - `useModal`, `useKeyboardShortcut`, and overflow helpers for UI behavior
   - `src/components/ErrorBoundary.jsx` and global notice/banner components provide shared error handling and messaging across the SPA.

10. **Internationalization and static assets**
   - Localization is built into the app via `src/i18n/config.js` and translation files in `public/locales/*`.
   - `public` also holds static assets such as icons, emotes, badges, stamps, rules markdown, and the site manifest.
   - This means some content is served as static frontend resources, while other content is fetched dynamically from the backend.

11. **Documentation and API discovery**
   - `public/swagger/swagger.json` and `src/pages/ApiDoc.jsx` indicate the frontend includes an API documentation surface.
   - `public/md/rules.md` and pages like Rules/FAQ/LegalNotice suggest content that is partly static and partly app-rendered, but still delivered through the frontend shell.

12. **Operational/runtime context**
   - The app is run with `npm start` as a local React dev server, with the backend and database expected to be running separately.
   - `.env` and `.env.production` imply environment-based configuration for API endpoints and runtime settings.
   - GitHub Actions in `.github/workflows/ci.yml` provides automated CI for this frontend repository.

13. **Important architecture takeaway**
   - For diagramming, treat this repo as a **presentation/client layer** with several feature modules sharing one backend API.
   - The main structural axes are:
     - route pages
     - reusable UI/domain components
     - API/auth/settings hooks
     - static i18n/assets
     - specialized map visualization
     - admin/moderation workflows

Main entry points: [`src/App.js`](https://github.com/viddie/goldberries-frontend/blob/master/src/App.js) (App), [`src/util/api.js`](https://github.com/viddie/goldberries-frontend/blob/master/src/util/api.js) (API client), [`src/pages/Challenge.jsx`](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Challenge.jsx) (Challenge), [`src/hooks/AuthProvider.jsx`](https://github.com/viddie/goldberries-frontend/blob/master/src/hooks/AuthProvider.jsx) (App hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_src_index["index<br/>entrypoint<br/>[index.js]"]
  node_src_app["App<br/>shell/router<br/>[App.js]"]
end

subgraph group_pages["Pages"]
  node_src_pages_index["Home<br/>landing page<br/>[Index.jsx]"]
  node_src_pages_challenge["Challenge<br/>detail page<br/>[Challenge.jsx]"]
  node_src_pages_campaign["Campaign<br/>detail page<br/>[Campaign.jsx]"]
  node_src_pages_mapviewer["Map Viewer<br/>visualization page<br/>[MapViewer.jsx]"]
  node_src_pages_submission["Submission<br/>workflow page<br/>[Submission.jsx]"]
  node_src_pages_submit["Submit<br/>workflow page<br/>[Submit.jsx]"]
  node_src_pages_player["Player<br/>profile page<br/>[Player.jsx]"]
  node_src_pages_search["Search<br/>discovery page<br/>[Search.jsx]"]
  node_src_pages_stats["Stats<br/>analytics page<br/>[Stats.jsx]"]
  node_src_pages_suggestions["Suggestions<br/>community page<br/>[Suggestions.jsx]"]
  node_src_pages_manage["Admin<br/>moderation area<br/>[Actions.jsx]"]
end

subgraph group_components["Components"]
  node_src_components_basic["Basic UI<br/>ui primitives<br/>[index.js]"]
  node_src_components_goldberries["Domain UI<br/>domain widgets<br/>[index.js]"]
  node_src_components_forms["Forms<br/>[Submission.jsx]"]
  node_src_components_submit["Submission UI<br/>workflow widgets<br/>[index.js]"]
  node_src_components_mapdata["Map Data<br/>viewer subsystem<br/>[MapDataViewer.jsx]"]
  node_src_components_mapimage["Map Images<br/>gallery subsystem<br/>[index.js]"]
  node_src_components_stats["Stats UI<br/>analytics widgets<br/>[Stats.jsx]"]
  node_src_components_suggestions["Suggestions UI<br/>proposal workflow"]
end

subgraph group_services["Services"]
  node_src_hooks["App hooks<br/>state/services<br/>[AuthProvider.jsx]"]
  node_src_api["API client<br/>http boundary<br/>[api.js]"]
end

subgraph group_static["Static assets"]
  node_src_i18n["i18n<br/>localization config<br/>[config.js]"]
  node_public_locales["Locales<br/>translation assets<br/>[translation.json]"]
  node_public_swagger["API docs<br/>static docs<br/>[swagger.json]"]
  node_public_rules["Rules md<br/>static content<br/>[rules.md]"]
end

node_src_index -->|"mounts"| node_src_app
node_src_app -->|"routes"| node_src_pages_index
node_src_app -->|"routes"| node_src_pages_challenge
node_src_app -->|"routes"| node_src_pages_campaign
node_src_app -->|"routes"| node_src_pages_mapviewer
node_src_app -->|"routes"| node_src_pages_submission
node_src_app -->|"routes"| node_src_pages_submit
node_src_app -->|"routes"| node_src_pages_player
node_src_app -->|"routes"| node_src_pages_search
node_src_app -->|"routes"| node_src_pages_stats
node_src_app -->|"routes"| node_src_pages_suggestions
node_src_app -->|"routes"| node_src_pages_manage
node_src_app -->|"uses"| node_src_hooks
node_src_app -->|"reads config"| node_src_api
node_src_pages_challenge -->|"renders"| node_src_components_goldberries
node_src_pages_submit -->|"uses"| node_src_components_forms
node_src_pages_submission -->|"uses"| node_src_components_submit
node_src_pages_mapviewer -->|"uses"| node_src_components_mapdata
node_src_pages_campaign -->|"uses"| node_src_components_mapimage
node_src_pages_stats -->|"uses"| node_src_components_stats
node_src_pages_suggestions -->|"uses"| node_src_components_suggestions
node_src_pages_manage -->|"uses"| node_src_components_forms
node_src_components_mapdata -->|"fetches"| node_src_api
node_src_components_mapimage -->|"fetches"| node_src_api
node_src_components_forms -->|"submits"| node_src_api
node_src_components_submit -->|"submits"| node_src_api
node_src_hooks -->|"wraps"| node_src_api
node_src_hooks -->|"supports"| node_src_i18n
node_src_i18n -->|"loads"| node_public_locales
node_src_pages_index -->|"links"| node_public_rules
node_src_pages_challenge -->|"references"| node_public_swagger

click node_src_index "https://github.com/viddie/goldberries-frontend/blob/master/src/index.js"
click node_src_app "https://github.com/viddie/goldberries-frontend/blob/master/src/App.js"
click node_src_pages_index "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Index.jsx"
click node_src_pages_challenge "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Challenge.jsx"
click node_src_pages_campaign "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Campaign.jsx"
click node_src_pages_mapviewer "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/MapViewer.jsx"
click node_src_pages_submission "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Submission.jsx"
click node_src_pages_submit "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Submit.jsx"
click node_src_pages_player "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Player.jsx"
click node_src_pages_search "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Search.jsx"
click node_src_pages_stats "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Stats.jsx"
click node_src_pages_suggestions "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Suggestions.jsx"
click node_src_pages_manage "https://github.com/viddie/goldberries-frontend/blob/master/src/pages/manage/Actions.jsx"
click node_src_components_basic "https://github.com/viddie/goldberries-frontend/blob/master/src/components/basic/index.js"
click node_src_components_goldberries "https://github.com/viddie/goldberries-frontend/blob/master/src/components/goldberries/index.js"
click node_src_components_forms "https://github.com/viddie/goldberries-frontend/blob/master/src/components/forms/Submission.jsx"
click node_src_components_submit "https://github.com/viddie/goldberries-frontend/blob/master/src/components/submit/index.js"
click node_src_components_mapdata "https://github.com/viddie/goldberries-frontend/blob/master/src/components/map_data/MapDataViewer.jsx"
click node_src_components_mapimage "https://github.com/viddie/goldberries-frontend/blob/master/src/components/map_image/index.js"
click node_src_components_stats "https://github.com/viddie/goldberries-frontend/blob/master/src/components/stats_page/Stats.jsx"
click node_src_components_suggestions "https://github.com/viddie/goldberries-frontend/blob/master/src/components/suggestions_page/SuggestionsList.jsx"
click node_src_hooks "https://github.com/viddie/goldberries-frontend/blob/master/src/hooks/AuthProvider.jsx"
click node_src_api "https://github.com/viddie/goldberries-frontend/blob/master/src/util/api.js"
click node_src_i18n "https://github.com/viddie/goldberries-frontend/blob/master/src/i18n/config.js"
click node_public_locales "https://github.com/viddie/goldberries-frontend/blob/master/public/locales/en/translation.json"
click node_public_swagger "https://github.com/viddie/goldberries-frontend/blob/master/public/swagger/swagger.json"
click node_public_rules "https://github.com/viddie/goldberries-frontend/blob/master/public/md/rules.md"

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_src_index,node_src_app toneBlue
class node_src_pages_index,node_src_pages_challenge,node_src_pages_campaign,node_src_pages_mapviewer,node_src_pages_submission,node_src_pages_submit,node_src_pages_player,node_src_pages_search,node_src_pages_stats,node_src_pages_suggestions,node_src_pages_manage toneAmber
class node_src_components_basic,node_src_components_goldberries,node_src_components_forms,node_src_components_submit,node_src_components_mapdata,node_src_components_mapimage,node_src_components_stats,node_src_components_suggestions toneMint
class node_src_hooks,node_src_api toneRose
class node_src_i18n,node_public_locales,node_public_swagger,node_public_rules toneIndigo
```

## Components

### App shell

Entry points, routing, and global providers.

- [index](https://github.com/viddie/goldberries-frontend/blob/master/src/index.js): entrypoint · Bootstraps the React app. · `src/index.js`
- [App](https://github.com/viddie/goldberries-frontend/blob/master/src/App.js): shell/router · Wires routing, providers, and global styling. · `src/App.js`

### Pages

Route-level screens and workflows.

- [Home](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Index.jsx): landing page · Front page and app entry navigation. · `src/pages/Index.jsx`
- [Challenge](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Challenge.jsx): detail page · Challenge detail and associated community activity. · `src/pages/Challenge.jsx`
- [Campaign](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Campaign.jsx): detail page · Campaign overview and related maps/challenges. · `src/pages/Campaign.jsx`
- [Map Viewer](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/MapViewer.jsx): visualization page · Interactive map inspection and rendering page. · `src/pages/MapViewer.jsx`
- [Submission](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Submission.jsx): workflow page · Submission detail and verification workflow. · `src/pages/Submission.jsx`
- [Submit](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Submit.jsx): workflow page · Submission creation flow. · `src/pages/Submit.jsx`
- [Player](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Player.jsx): profile page · Player profile and linked completions. · `src/pages/Player.jsx`
- [Search](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Search.jsx): discovery page · Search and filtering across repository data. · `src/pages/Search.jsx`
- [Stats](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Stats.jsx): analytics page · Aggregated statistics and charts. · `src/pages/Stats.jsx`
- [Suggestions](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/Suggestions.jsx): community page · Suggestion creation and review flows. · `src/pages/Suggestions.jsx`
- [Admin](https://github.com/viddie/goldberries-frontend/blob/master/src/pages/manage/Actions.jsx): moderation area · Privileged management and moderation workflows. · `src/pages/manage/Actions.jsx`

### Components

Shared UI, domain widgets, and feature modules.

- [Basic UI](https://github.com/viddie/goldberries-frontend/blob/master/src/components/basic/index.js): ui primitives · Generic layout, buttons, links, feedback, and utility widgets. · `src/components/basic/index.js`
- [Domain UI](https://github.com/viddie/goldberries-frontend/blob/master/src/components/goldberries/index.js): domain widgets · Reusable goldberries-specific chips, selects, embeds, and icons. · `src/components/goldberries/index.js`
- [Forms](https://github.com/viddie/goldberries-frontend/blob/master/src/components/forms/Submission.jsx): editor forms · Structured create/edit forms for core domain objects. · `src/components/forms/Submission.jsx`
- [Submission UI](https://github.com/viddie/goldberries-frontend/blob/master/src/components/submit/index.js): workflow widgets · Single and multi-submission interaction components. · `src/components/submit/index.js`
- [Map Data](https://github.com/viddie/goldberries-frontend/blob/master/src/components/map_data/MapDataViewer.jsx): viewer subsystem · Interactive map data viewer, controls, and renderers. · `src/components/map_data/MapDataViewer.jsx`
- [Map Images](https://github.com/viddie/goldberries-frontend/blob/master/src/components/map_image/index.js): gallery subsystem · Campaign and map image rendering and gallery views. · `src/components/map_image/index.js`
- [Stats UI](https://github.com/viddie/goldberries-frontend/blob/master/src/components/stats_page/Stats.jsx): analytics widgets · Tabbed charts and statistics displays. · `src/components/stats_page/Stats.jsx`
- [Suggestions UI](https://github.com/viddie/goldberries-frontend/blob/master/src/components/suggestions_page/SuggestionsList.jsx): proposal workflow · Suggestion modals and forms for challenge/features proposals. · `src/components/suggestions_page/SuggestionsList.jsx`

### Services

API access, hooks, and cross-cutting app state.

- [App hooks](https://github.com/viddie/goldberries-frontend/blob/master/src/hooks/AuthProvider.jsx): state/services · Authentication, settings, API, and UI behavior hooks/providers. · `src/hooks/AuthProvider.jsx`
- [API client](https://github.com/viddie/goldberries-frontend/blob/master/src/util/api.js): http boundary · Central backend request layer. · `src/util/api.js`

### Static assets

Localization, public content, and documentation assets.

- [i18n](https://github.com/viddie/goldberries-frontend/blob/master/src/i18n/config.js): localization config · Translation setup and locale loading. · `src/i18n/config.js`
- [Locales](https://github.com/viddie/goldberries-frontend/blob/master/public/locales/en/translation.json): translation assets · Compiled translation files for supported languages. · `public/locales/en/translation.json`
- [API docs](https://github.com/viddie/goldberries-frontend/blob/master/public/swagger/swagger.json): static docs · Published Swagger spec surfaced by the frontend. · `public/swagger/swagger.json`
- [Rules md](https://github.com/viddie/goldberries-frontend/blob/master/public/md/rules.md): static content · Markdown rules content served with the app. · `public/md/rules.md`

## Connections

- index → App: mounts · Bootstraps the SPA and renders the application shell.
- App → Home: routes · App shell routes users to the home page.
- App → Challenge: routes · App shell routes to challenge detail pages.
- App → Campaign: routes · App shell routes to campaign pages.
- App → Map Viewer: routes · App shell routes to the map viewer.
- App → Submission: routes · App shell routes to submission views.
- App → Submit: routes · App shell routes to submission creation.
- App → Player: routes · App shell routes to player profiles.
- App → Search: routes · App shell routes to search.
- App → Stats: routes · App shell routes to statistics dashboards.
- App → Suggestions: routes · App shell routes to suggestions workflows.
- App → Admin: routes · App shell routes privileged admin flows.
- App → App hooks: uses · App shell depends on global providers and hooks.
- App → API client: reads config · App shell and pages use the backend API boundary.
- Challenge → Domain UI: renders · Challenge pages use domain-specific badges, chips, and selects.
- Submit → Forms: uses · Submission creation relies on structured form components.
- Submission → Submission UI: uses · Submission detail pages use submission workflow widgets.
- Map Viewer → Map Data: uses · Map viewer pages rely on the interactive visualization subsystem.
- Campaign → Map Images: uses · Campaign pages use map image and gallery components.
- Stats → Stats UI: uses · Stats pages render the analytics widgets.
- Suggestions → Suggestions UI: uses · Suggestions pages rely on proposal UI components.
- Admin → Forms: uses · Admin workflows reuse the core edit forms.
- Map Data → API client: fetches · Viewer loads structured map data from the backend.
- Map Images → API client: fetches · Image/gallery views load campaign and map assets through the API boundary.
- Forms → API client: submits · Forms create and edit backend records.
- Submission UI → API client: submits · Submission workflows persist data through the API.
- App hooks → API client: wraps · Custom hooks centralize authenticated HTTP access.
- App hooks → i18n: supports · Providers and app state cooperate with localized UI.
- i18n → Locales: loads · i18n config loads translation assets from public locales.
- Home → Rules md: links · Front-end content surfaces static rules documentation.
- Challenge → API docs: references · API documentation is exposed alongside app workflows.