# anandavnish/progressshelf architecture

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

- Interactive diagram: https://gitdiagram.com/anandavnish/progressshelf
- Repository: https://github.com/anandavnish/progressshelf

## Overview

1. **What this repo is**
   - ProgressShelf is a **static, browser-only progress tracking app**. There is no backend service in this repository beyond optional Firebase usage; the app runs from HTML/CSS/ES modules and is deployable on GitHub Pages.

2. **Primary runtime surfaces**
   - `index.html` is the **entry/landing page** for sign-in or guest access.
   - `dashboard.html` is the **main application surface** where trackers are displayed and managed.
   - Both pages are driven by the root-level `app.js`, `auth.js`, `db.js`, and `index.css`.

3. **Core client-side subsystems**
   - `auth.js` handles **authentication routing and session state**: Google sign-in when Firebase is configured, or guest/sandbox mode when it is not.
   - `db.js` is the **persistence abstraction**. It hides whether data comes from Firestore or browser storage.
   - `app.js` is the **presentation and interaction layer**: rendering cards, handling actions, filtering/searching, and live deadline/progress behaviors.

4. **Data flow at a high level**
   - User actions originate in the browser UI.
   - `auth.js` determines whether the user is a Firebase-authenticated user or a guest.
   - `db.js` stores and retrieves tracker data from either **Cloud Firestore** or **localStorage/sessionStorage**.
   - `app.js` consumes that data to render the dashboard and keep the view in sync with edits, filters, and timers.

5. **State and persistence boundaries**
   - The repo intentionally separates **cloud-synced state** from **local sandbox state**.
   - Firebase-backed data is used for signed-in users.
   - Guest mode data stays entirely in the browser and is never sent to a server.
   - `firebase-config.js` is not committed; `firebase-config.template.js` documents the required shape for local setup.

6. **Dashboard feature set**
   - The main dashboard supports multiple tracker types: **progress goals, task checklists, and quick notes**.
   - It also includes **global search**, **stats-based filtering**, inline deletion confirmation, collapsible content for long cards, and animated deadline indicators.
   - These are UI concerns concentrated in `app.js` and styled by `index.css`.

7. **Visual and interaction system**
   - `index.css` provides the design system: dark theme tokens, glassmorphism-style surfaces, responsive layout, card styling, animations, and the animated progress/deadline visuals.
   - The README notes a self-contained animated logo SVG, but the main app styling is centralized in the shared CSS.

8. **Versioned architecture**
   - The `versions/` directory preserves frozen releases:
     - `versions/v1.0/` is the original minimal app.
     - `versions/v2.0/` is the deadline-focused stable release.
   - Each archived version is a **self-contained copy** of the same app structure, including its own HTML, JS, CSS, and Firebase config template.

9. **Deployment model**
   - `.github/workflows/deploy.yml` indicates automated deployment to a static host, consistent with GitHub Pages.
   - `.nojekyll` confirms the site is served as plain static files without Jekyll processing.
   - This means the architecture has **no server-side render step, no build step, and no API backend in-repo**.

10. **External service boundary**
   - The only material external service is **Firebase**, used for Google authentication and Firestore persistence when enabled.
   - In the default guest path, the app degrades gracefully to local browser storage, so the same UI and interaction model works offline or without setup.

11. **What to show in an architecture diagram**
   - Model the app as three browser-facing layers: **entry/auth page**, **dashboard UI**, and **persistence/auth services**.
   - Show Firebase as an optional external dependency behind `auth.js`/`db.js`.
   - Show `app.js` as the central orchestrator connecting UI events, tracker state, filters/search, and rendering.
   - Show `versions/` as isolated historical snapshots, not runtime dependencies of the latest app.

Main entry points: [`app.js`](https://github.com/anandavnish/progressshelf/blob/main/app.js) (App logic), [`index.html`](https://github.com/anandavnish/progressshelf/blob/main/index.html) (Landing page), [`.github/workflows/deploy.yml`](https://github.com/anandavnish/progressshelf/blob/main/.github/workflows/deploy.yml) (Deploy workflow), [`auth.js`](https://github.com/anandavnish/progressshelf/blob/main/auth.js) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_browser["Browser app"]
  node_index_html["Landing page<br/>html entry<br/>[index.html]"]
  node_dashboard_html["Dashboard<br/>html app surface<br/>[dashboard.html]"]
  node_app_js["App logic<br/>ui orchestrator<br/>[app.js]"]
  node_index_css["Styles<br/>design system<br/>[index.css]"]
end

subgraph group_g_runtime["Runtime services"]
  node_auth_js["Auth<br/>session routing<br/>[auth.js]"]
  node_db_js["Data store<br/>persistence adapter<br/>[db.js]"]
  node_firebase_cfg["Config template<br/>setup template"]
  node_firebase[("Firebase<br/>external service")]
end

subgraph group_g_ops["Deployment"]
  node_deploy_wf["Deploy workflow<br/>ci deploy<br/>[deploy.yml]"]
  node_nojekyll[".nojekyll<br/>static host hint<br/>[.nojekyll]"]
end

subgraph group_g_archives["Archived versions"]
  node_v1_snapshot["v1.0<br/>archived release<br/>[v1.0]"]
  node_v2_snapshot["v2.0<br/>archived release<br/>[v2.0]"]
end

node_index_html -->|"sign-in / guest"| node_auth_js
node_index_html -->|"bootstrap"| node_app_js
node_dashboard_html -->|"loads"| node_app_js
node_dashboard_html -->|"styles"| node_index_css
node_index_html -->|"styles"| node_index_css
node_app_js -->|"reads / writes"| node_db_js
node_auth_js -->|"session scope"| node_db_js
node_auth_js -.->|"optional auth"| node_firebase
node_db_js -.->|"optional Firestore"| node_firebase
node_db_js -->|"configured by"| node_firebase_cfg
node_app_js -->|"user state"| node_auth_js
node_app_js -->|"renders"| node_index_css
node_deploy_wf -->|"publishes"| node_index_html
node_deploy_wf -->|"publishes"| node_dashboard_html
node_deploy_wf -->|"publishes"| node_app_js
node_nojekyll -->|"supports"| node_deploy_wf
node_v1_snapshot -.->|"evolves to"| node_v2_snapshot

click node_index_html "https://github.com/anandavnish/progressshelf/blob/main/index.html"
click node_dashboard_html "https://github.com/anandavnish/progressshelf/blob/main/dashboard.html"
click node_app_js "https://github.com/anandavnish/progressshelf/blob/main/app.js"
click node_index_css "https://github.com/anandavnish/progressshelf/blob/main/index.css"
click node_auth_js "https://github.com/anandavnish/progressshelf/blob/main/auth.js"
click node_db_js "https://github.com/anandavnish/progressshelf/blob/main/db.js"
click node_firebase_cfg "https://github.com/anandavnish/progressshelf/blob/main/firebase-config.template.js"
click node_deploy_wf "https://github.com/anandavnish/progressshelf/blob/main/.github/workflows/deploy.yml"
click node_nojekyll "https://github.com/anandavnish/progressshelf/blob/main/.nojekyll"
click node_v1_snapshot "https://github.com/anandavnish/progressshelf/blob/main/versions/v1.0"
click node_v2_snapshot "https://github.com/anandavnish/progressshelf/blob/main/versions/v2.0"

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_index_html,node_dashboard_html,node_app_js,node_index_css toneBlue
class node_auth_js,node_db_js,node_firebase_cfg,node_firebase toneAmber
class node_deploy_wf,node_nojekyll toneMint
class node_v1_snapshot,node_v2_snapshot toneRose
```

## Components

### Browser app

Static client-side surfaces and shared presentation logic.

- [Landing page](https://github.com/anandavnish/progressshelf/blob/main/index.html): html entry · Sign-in and guest entry surface. · `index.html`
- [Dashboard](https://github.com/anandavnish/progressshelf/blob/main/dashboard.html): html app surface · Main tracker management page. · `dashboard.html`
- [App logic](https://github.com/anandavnish/progressshelf/blob/main/app.js): ui orchestrator · Renders trackers, handles interactions, filtering, and live updates. · `app.js`
- [Styles](https://github.com/anandavnish/progressshelf/blob/main/index.css): design system · Shared visual theme, layout, and animations. · `index.css`

### Runtime services

Authentication, persistence, and optional cloud dependencies.

- [Auth](https://github.com/anandavnish/progressshelf/blob/main/auth.js): session routing · Chooses Firebase sign-in or guest mode and manages session state. · `auth.js`
- [Data store](https://github.com/anandavnish/progressshelf/blob/main/db.js): persistence adapter · Abstracts Firestore versus browser storage. · `db.js`
- [Config template](https://github.com/anandavnish/progressshelf/blob/main/firebase-config.template.js): setup template · Documents the optional Firebase configuration shape. · `firebase-config.template.js`
- **Firebase**: external service · Optional Google auth and Firestore backend.

### Deployment

Static hosting and release automation.

- [Deploy workflow](https://github.com/anandavnish/progressshelf/blob/main/.github/workflows/deploy.yml): ci deploy · Automates static deployment to GitHub Pages. · `.github/workflows/deploy.yml`
- [.nojekyll](https://github.com/anandavnish/progressshelf/blob/main/.nojekyll): static host hint · Ensures plain static file serving without Jekyll processing. · `.nojekyll`

### Archived versions

Frozen historical snapshots of earlier app releases.

- [v1.0](https://github.com/anandavnish/progressshelf/blob/main/versions/v1.0): archived release · Original minimal app snapshot. · `versions/v1.0`
- [v2.0](https://github.com/anandavnish/progressshelf/blob/main/versions/v2.0): archived release · Deadline-focused stable snapshot. · `versions/v2.0`

## Connections

- Landing page → Auth: sign-in / guest · Entry page hands off to authentication routing.
- Landing page → App logic: bootstrap · Loads shared client logic for the browser app.
- Dashboard → App logic: loads · Dashboard page is driven by the central app controller.
- Dashboard → Styles: styles · Dashboard uses the shared visual system.
- Landing page → Styles: styles · Landing page shares the same theme.
- App logic → Data store: reads / writes · App state is synchronized through the persistence abstraction.
- Auth → Data store: session scope · Authentication mode determines which storage backend is used.
- Auth → Firebase: optional auth · Google sign-in is enabled when Firebase is configured.
- Data store → Firebase: optional Firestore · Signed-in users can persist data in Firestore.
- Data store → Config template: configured by · Firebase setup is driven by the local config template.
- App logic → Auth: user state · UI behavior depends on current authentication mode.
- App logic → Styles: renders · Interaction states and tracker visuals are styled centrally.
- Deploy workflow → Landing page: publishes · Deployment serves the static entry page and bundled assets.
- Deploy workflow → Dashboard: publishes · Deployment serves the dashboard surface.
- Deploy workflow → App logic: publishes · Deployment includes the client runtime modules.
- .nojekyll → Deploy workflow: supports · Static hosting is configured to bypass Jekyll.
- v1.0 → v2.0: evolves to · Archived releases show the app's historical progression.