How anandavnish/progressshelf works
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 App logic · index.html Landing page · deploy.yml Deploy workflow · auth.js Auth
Components 12
Browser app
Static client-side surfaces and shared presentation logic.
- Landing page · Sign-in and guest entry surface.
index.html - Dashboard · Main tracker management page.
dashboard.html - App logic · Renders trackers, handles interactions, filtering, and live updates.
app.js - Styles · Shared visual theme, layout, and animations.
index.css
Runtime services
Authentication, persistence, and optional cloud dependencies.
- Auth · Chooses Firebase sign-in or guest mode and manages session state.
auth.js - Data store · Abstracts Firestore versus browser storage.
db.js - Config template · Documents the optional Firebase configuration shape.
firebase-config.template.js - Firebase · Optional Google auth and Firestore backend.
Deployment
Static hosting and release automation.
- Deploy workflow · Automates static deployment to GitHub Pages.
.github/workflows/deploy.yml - .nojekyll · Ensures plain static file serving without Jekyll processing.
.nojekyll
Connections 17
- 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.