# roxannefranco/gamernaut architecture

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

- Interactive diagram: https://gitdiagram.com/roxannefranco/gamernaut
- Repository: https://github.com/roxannefranco/gamernaut

## Overview

1. **Project shape**
   - This is a **multi-page front-end auction app** built with **Vite** and plain **JavaScript modules**.
   - Each major screen has its own HTML entry point in `src/` (`index.html`, `login.html`, `register.html`, `new.html`, `edit.html`, `profile.html`, `single.html`), which keeps routing simple and page-specific.

2. **Primary application boundaries**
   - The code is separated into three main layers:
     - **Page controllers** in `src/js/pages/`
     - **Reusable UI blocks/components** in `src/js/blocks/`
     - **API adapters** in `src/js/api/`
   - This makes the architecture easy to diagram as: browser page → page module → API call + block rendering.

3. **Page-level orchestration**
   - `src/js/pages/*.mjs` contains the logic for each screen:
     - landing/listings view
     - login/register flows
     - create/edit listing forms
     - single listing detail view
     - user profile view
   - These modules likely coordinate fetching data, reading auth state, and inserting reusable blocks into the page DOM.

4. **Reusable UI system**
   - `src/js/blocks/` holds shared presentation pieces such as:
     - header/footer
     - logo/icons
     - auth banner
     - listing gallery/panel
     - single listing content
   - These are the reusable rendering units used across pages, which reduces duplication and keeps consistent layout and styling.

5. **Data access layer**
   - `src/js/api/` isolates all server communication:
     - authentication: login/register and token-related operations
     - listings: get all, get single, create, edit, delete
     - bidding: add bid
     - user profile and avatar update
   - This is the main boundary between the UI and the backend auction service. The page modules depend on these functions rather than calling `fetch` directly.

6. **Domain flow: listings and bids**
   - The central user flow is:
     - browse listings on the home page
     - open a single listing
     - authenticate if needed
     - place a bid or manage owned listings
   - The app’s core data model is therefore around **listings, bids, users, and credits**.

7. **Authentication and user state**
   - Auth is a first-class subsystem, split across `authentication.mjs`, `login.mjs`, `register.mjs`, and `getUserProfile.mjs`.
   - The readme indicates authenticated users get **starting credits**, can bid, and can create/edit/delete their own listings.
   - UI state changes such as showing/hiding the auth banner or user-specific actions are likely driven by the auth token and profile data.

8. **Page-specific feature set**
   - `new.mjs` and `edit.mjs` support listing management.
   - `single.mjs` and `singleContent.mjs` handle listing detail, author/bid history, and bid submission.
   - `profile.mjs` presents the signed-in user’s listings and account information.
   - This suggests a clear separation between browsing, account management, and content ownership flows.

9. **Styling and assets**
   - Styling is centralized in `src/css/app.css`, with `postcss.config.cjs` and `tailwind.config.cjs` indicating Tailwind/PostCSS-based styling.
   - Static assets live under `src/public/img`, while icons/logos are encapsulated in blocks rather than being scattered through page code.
   - The visual layer is therefore mostly componentized and utility-driven rather than template-heavy.

10. **Build and tooling**
   - The repo uses **Vite** for dev server/build bundling.
   - `eslint`, `prettier`, and Husky pre-commit hooks indicate code quality enforcement before commits.
   - These tools affect development workflow, but not runtime architecture.

11. **Runtime and deployment model**
   - Because the app is composed of multiple HTML entry files, it behaves like a **static front-end site** that talks to an external backend API.
   - The repo itself does not show backend implementation; the API layer is the integration boundary to that service.
   - Netlify hosting from the readme matches this static-frontend deployment model.

12. **How to diagram the system**
   - A good architecture diagram would show:
     - browser user navigating between HTML pages
     - each page bootstrapping a page module
     - page modules using shared blocks for rendering
     - page modules calling API adapters
     - API adapters communicating with the remote auction backend
     - auth token/profile state influencing what actions and UI are available

Main entry points: [`src/js/pages/single.mjs`](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/single.mjs) (Single controller), [`src/js/pages/index.mjs`](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/index.mjs) (Index controller), [`src/js/pages/profile.mjs`](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/profile.mjs) (Profile controller), [`src/js/api/getListings.mjs`](https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/getListings.mjs) (Listings API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Entry screens"]
  node_n1["Site pages<br/>multi-page entry"]
  node_n2["Home page<br/>html entry<br/>[index.html]"]
  node_n3["Auth pages<br/>html entries"]
  node_n4["Listing pages<br/>html entries"]
  node_n5["Profile page<br/>html entry<br/>[profile.html]"]
end

subgraph group_g2["Page controllers"]
  node_n6["Index controller<br/>page module<br/>[index.mjs]"]
  node_n7["Auth controller<br/>page module"]
  node_n8["Listing editor<br/>page module"]
  node_n9["Single controller<br/>page module<br/>[single.mjs]"]
  node_n10["Profile controller<br/>page module<br/>[profile.mjs]"]
end

subgraph group_g3["UI blocks"]
  node_n11["Auth banner<br/>shared block<br/>[authBanner.mjs]"]
  node_n12["Header/Footer<br/>layout blocks"]
  node_n13["Gallery/Panel<br/>listing blocks<br/>[gallery.mjs]"]
  node_n14["Single content<br/>detail block<br/>[singleContent.mjs]"]
end

subgraph group_g4["API adapters"]
  node_n15["Auth API<br/>auth adapter<br/>[authentication.mjs]"]
  node_n16["Listings API<br/>listing adapter<br/>[getListings.mjs]"]
  node_n17["Bids API<br/>bid adapter<br/>[addBid.mjs]"]
  node_n18["Profile API<br/>user adapter<br/>[getUserProfile.mjs]"]
end

subgraph group_g5["Shared core"]
  node_n19["App config<br/>shared config<br/>[config.mjs]"]
  node_n20["Helpers<br/>shared utils<br/>[functions.mjs]"]
end

subgraph group_g6["Styles and assets"]
  node_n21["Global CSS<br/>styles<br/>[app.css]"]
  node_n22[("Static assets<br/>images")]
end

node_n1 -->|"bootstraps"| node_n6
node_n1 -->|"boots"| node_n7
node_n1 -->|"boots"| node_n8
node_n1 -->|"boots"| node_n9
node_n1 -->|"boots"| node_n10
node_n6 -->|"renders"| node_n13
node_n6 -->|"reads"| node_n16
node_n7 -->|"authenticates"| node_n15
node_n8 -->|"mutates"| node_n16
node_n9 -->|"renders"| node_n14
node_n9 -->|"reads"| node_n16
node_n9 -->|"submits"| node_n17
node_n10 -->|"reads"| node_n18
node_n10 -->|"reads"| node_n16
node_n6 -->|"shows"| node_n11
node_n7 -->|"updates"| node_n11
node_n8 -->|"updates"| node_n11
node_n9 -->|"shows"| node_n11
node_n10 -->|"shows"| node_n11
node_n6 -->|"uses"| node_n12
node_n9 -->|"uses"| node_n12
node_n10 -->|"uses"| node_n12
node_n6 -->|"styled by"| node_n21
node_n9 -->|"styled by"| node_n21
node_n10 -->|"styled by"| node_n21
node_n13 -->|"uses"| node_n22
node_n14 -->|"uses"| node_n22
node_n15 -->|"configured by"| node_n19
node_n16 -->|"configured by"| node_n19
node_n17 -->|"configured by"| node_n19
node_n18 -->|"configured by"| node_n19
node_n15 -->|"uses"| node_n20
node_n16 -->|"uses"| node_n20
node_n17 -->|"uses"| node_n20
node_n18 -->|"uses"| node_n20

click node_n2 "https://github.com/roxannefranco/gamernaut/blob/main/src/index.html"
click node_n5 "https://github.com/roxannefranco/gamernaut/blob/main/src/profile.html"
click node_n6 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/index.mjs"
click node_n9 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/single.mjs"
click node_n10 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/profile.mjs"
click node_n11 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/authBanner.mjs"
click node_n13 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/gallery.mjs"
click node_n14 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/singleContent.mjs"
click node_n15 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/authentication.mjs"
click node_n16 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/getListings.mjs"
click node_n17 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/addBid.mjs"
click node_n18 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/getUserProfile.mjs"
click node_n19 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/config.mjs"
click node_n20 "https://github.com/roxannefranco/gamernaut/blob/main/src/js/functions.mjs"
click node_n21 "https://github.com/roxannefranco/gamernaut/blob/main/src/css/app.css"
click node_n22 "https://github.com/roxannefranco/gamernaut/tree/main/src/public/img"

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_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n6,node_n7,node_n8,node_n9,node_n10 toneAmber
class node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n17,node_n18 toneRose
class node_n19,node_n20 toneIndigo
class node_n21,node_n22 toneTeal
```

## Components

### Entry screens

HTML entry points for the multi-page app

- **Site pages**: multi-page entry · Separate HTML screens for browsing, auth, listings, and profile flows
- [Home page](https://github.com/roxannefranco/gamernaut/blob/main/src/index.html): html entry · Landing and listings screen · `src/index.html`
- **Auth pages**: html entries · Login and registration screens
- **Listing pages**: html entries · Create, edit, and single-listing screens
- [Profile page](https://github.com/roxannefranco/gamernaut/blob/main/src/profile.html): html entry · Signed-in user account screen · `src/profile.html`

### Page controllers

Screen-level orchestration modules

- [Index controller](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/index.mjs): page module · Bootstraps the home/listings view · `src/js/pages/index.mjs`
- **Auth controller**: page module · Handles login and registration flows
- **Listing editor**: page module · Orchestrates create and edit listing forms
- [Single controller](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/single.mjs): page module · Drives listing detail and bid submission · `src/js/pages/single.mjs`
- [Profile controller](https://github.com/roxannefranco/gamernaut/blob/main/src/js/pages/profile.mjs): page module · Renders account info and owned listings · `src/js/pages/profile.mjs`

### UI blocks

Reusable presentation components

- [Auth banner](https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/authBanner.mjs): shared block · Shows session state and user actions · `src/js/blocks/authBanner.mjs`
- **Header/Footer**: layout blocks · Shared page chrome and navigation shell
- [Gallery/Panel](https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/gallery.mjs): listing blocks · Listing cards and collection display · `src/js/blocks/gallery.mjs`
- [Single content](https://github.com/roxannefranco/gamernaut/blob/main/src/js/blocks/singleContent.mjs): detail block · Listing detail, author info, history, and bid form · `src/js/blocks/singleContent.mjs`

### API adapters

Server communication boundary

- [Auth API](https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/authentication.mjs): auth adapter · Login, register, and session validation · `src/js/api/authentication.mjs`
- [Listings API](https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/getListings.mjs): listing adapter · Browse, create, edit, and delete listings · `src/js/api/getListings.mjs`
- [Bids API](https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/addBid.mjs): bid adapter · Submits bids against listings · `src/js/api/addBid.mjs`
- [Profile API](https://github.com/roxannefranco/gamernaut/blob/main/src/js/api/getUserProfile.mjs): user adapter · Loads profile data and updates avatar · `src/js/api/getUserProfile.mjs`

### Shared core

Cross-cutting utilities and configuration

- [App config](https://github.com/roxannefranco/gamernaut/blob/main/src/js/config.mjs): shared config · Central configuration and constants · `src/js/config.mjs`
- [Helpers](https://github.com/roxannefranco/gamernaut/blob/main/src/js/functions.mjs): shared utils · Common browser and data helpers · `src/js/functions.mjs`

### Styles and assets

Global styling and static media

- [Global CSS](https://github.com/roxannefranco/gamernaut/blob/main/src/css/app.css): styles · Primary stylesheet for the app · `src/css/app.css`
- [Static assets](https://github.com/roxannefranco/gamernaut/tree/main/src/public/img): images · Public images and media used by the UI · `src/public/img`

## Connections

- Site pages → Index controller: bootstraps · Home screen loads its page controller
- Site pages → Auth controller: boots · Auth screens load their page controllers
- Site pages → Listing editor: boots · Listing screens load their page controllers
- Site pages → Single controller: boots · Single listing screen loads its page controller
- Site pages → Profile controller: boots · Profile screen loads its page controller
- Index controller → Gallery/Panel: renders · Home controller renders listing collections
- Index controller → Listings API: reads · Home controller fetches listings data
- Auth controller → Auth API: authenticates · Login and register flows use auth adapters
- Listing editor → Listings API: mutates · Create and edit flows write listing data
- Single controller → Single content: renders · Single controller mounts detail content
- Single controller → Listings API: reads · Single view loads listing data
- Single controller → Bids API: submits · Single view sends bids
- Profile controller → Profile API: reads · Profile controller loads user profile
- Profile controller → Listings API: reads · Profile view can show owned listings
- Index controller → Auth banner: shows · Home screen displays auth state
- Auth controller → Auth banner: updates · Auth flows affect banner state
- Listing editor → Auth banner: updates · Listing management depends on session state
- Single controller → Auth banner: shows · Single view exposes authenticated actions
- Profile controller → Auth banner: shows · Profile screen reflects signed-in user state
- Index controller → Header/Footer: uses · Home view shares common chrome
- Single controller → Header/Footer: uses · Detail view shares common chrome
- Profile controller → Header/Footer: uses · Profile view shares common chrome
- Index controller → Global CSS: styled by · Pages use the global stylesheet
- Single controller → Global CSS: styled by · Pages use the global stylesheet
- Profile controller → Global CSS: styled by · Pages use the global stylesheet
- Gallery/Panel → Static assets: uses · Listing UI uses static images and media
- Single content → Static assets: uses · Detail UI uses static images and media
- Auth API → App config: configured by · API layer depends on shared config
- Listings API → App config: configured by · API layer depends on shared config
- Bids API → App config: configured by · API layer depends on shared config
- Profile API → App config: configured by · API layer depends on shared config
- Auth API → Helpers: uses · Auth adapter uses shared helpers
- Listings API → Helpers: uses · Listings adapter uses shared helpers
- Bids API → Helpers: uses · Bids adapter uses shared helpers
- Profile API → Helpers: uses · Profile adapter uses shared helpers