viddie/goldberries-frontend

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