# zamtls15/googlehelportal-v1 architecture

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

- Interactive diagram: https://gitdiagram.com/zamtls15/googlehelportal-v1
- Repository: https://github.com/zamtls15/googlehelportal-v1

## Overview

1. **Overall shape**
   - This repository is a **client-heavy member portal** with a small set of backend/API entry points.
   - The app is organized around **static HTML pages + JavaScript modules**, with **serverless API functions** for privileged operations.

2. **Primary user-facing surfaces**
   - `pages/login.html` is the entry point for sign-in.
   - `pages/user.html` is the authenticated member experience.
   - `pages/hq-control-7x9k.html` is a separate admin/control surface, intentionally obscurely named.
   - `index.html` likely serves as the root landing page or router entry, while `public/404.html` handles missing routes.

3. **Frontend module boundaries**
   - `js/auth.js` handles login/session behavior.
   - `js/user.js` drives the member dashboard experience.
   - `js/admin.js` drives the admin/control panel.
   - `js/firebase-config.js` centralizes client-side Firebase setup and is likely shared by the auth flow and page scripts.

4. **Authentication and session flow**
   - The README describes **email-based “magic code” sign-in**, so the login experience is likely passwordless or code/link based.
   - The flow is: user enters email → authentication provider sends code/link → user returns and is recognized → portal loads member badge/content.
   - Authentication state then determines whether the user sees the user page or the admin page.

5. **Backend/API responsibilities**
   - `api/send-welcome-email/index.js` is a server-side function for sending onboarding/welcome mail.
   - `api/manage-supabase-user/index.js` is a privileged endpoint for creating/updating/managing users in a Supabase-backed system.
   - `api/email-template.js` contains reusable email markup/content used by the email-sending flow.
   - These APIs are the main boundary where sensitive operations leave the browser.

6. **Data and identity model**
   - The README implies members have a “badge” with name, role, and medals, so the UI likely renders a profile-like record sourced from backend data.
   - The naming of `manage-supabase-user` suggests **Supabase** is the backend data store or user directory for member records.
   - Firebase appears to be used on the client side for authentication plumbing, while Supabase is used for member/admin data management.

7. **Admin workflow**
   - The “Space Captains” in the README map to the admin subsystem.
   - Admins likely create or update member accounts, trigger welcome emails, and assign roles/medals through the admin page.
   - This is the clearest trust boundary in the repo: normal users consume data, while admins invoke privileged API operations.

8. **Styling and shared presentation**
   - `pages/shared.css` is the main shared stylesheet for the page set.
   - `STYLES_DOCUMENTATION.md` indicates the styling system is documented separately, suggesting a deliberate shared UI layer rather than per-page styling.
   - The portal likely relies on consistent static-page styling instead of a component framework.

9. **Deployment and routing**
   - `vercel.json`, `public/_redirects`, and the `api/` folder indicate deployment to **Vercel-style static hosting with serverless functions**.
   - `public/404.html` and redirect rules suggest route handling is done at the edge/static-host layer, not by a full custom app server.
   - `server.js` and `.replit-artifact` imply local or alternative runtime support in addition to the hosted deployment.

10. **Runtime/tooling boundary**
   - `vite.config.js`, `package.json`, and `tsconfig.json` indicate a modern frontend build/dev setup, even though the app pages are plain HTML/JS.
   - The presence of Vite suggests local development/bundling support rather than a monolithic framework app.
   - The codebase is JavaScript-first, with TypeScript configuration present for tooling compatibility.

11. **External service dependencies**
   - **Firebase** is present in the client config and likely powers auth/session behavior.
   - **Supabase** is referenced by the admin-management API and likely stores member/user records.
   - **Email delivery** is part of the backend flow, probably used for onboarding and notifications.

12. **How to diagram the architecture**
   - Draw three main zones: **browser pages**, **serverless APIs**, and **external services**.
   - Show login/user/admin pages all sharing common JS/CSS and auth state.
   - Show authenticated/admin actions calling the API functions, which in turn call Supabase and email services.
   - Keep the admin path separate from the normal member path to reflect the intended privilege boundary.

Main entry points: [`server.js`](https://github.com/zamtls15/googlehelportal-v1/blob/main/server.js) (Local server), [`js/admin.js`](https://github.com/zamtls15/googlehelportal-v1/blob/main/js/admin.js) (Admin UI), [`pages/login.html`](https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/login.html) (Login), [`api/send-welcome-email/index.js`](https://github.com/zamtls15/googlehelportal-v1/blob/main/api/send-welcome-email/index.js) (Welcome email)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_index_page["Landing<br/>static page<br/>[index.html]"]
  node_login_page["Login<br/>static page<br/>[login.html]"]
  node_user_page["Member portal<br/>static page<br/>[user.html]"]
  node_admin_page["Control room<br/>static page"]
  node_shared_css["Shared CSS<br/>styles<br/>[shared.css]"]
  node_auth_js["Auth flow<br/>client module<br/>[auth.js]"]
  node_user_js["Member UI<br/>client module<br/>[user.js]"]
  node_admin_js["Admin UI<br/>client module<br/>[admin.js]"]
  node_firebase_cfg["Firebase config<br/>client config<br/>[firebase-config.js]"]
end

subgraph group_serverless["Serverless API"]
  node_welcome_api["Welcome email<br/>serverless fn<br/>[index.js]"]
  node_manage_user_api["User manager<br/>serverless fn<br/>[index.js]"]
  node_email_template["Email template<br/>shared mail<br/>[email-template.js]"]
end

subgraph group_external["External services"]
  node_firebase_service[("Firebase<br/>auth service")]
  node_supabase_service[("Supabase<br/>data service")]
  node_email_service["Email delivery<br/>mail provider"]
end

subgraph group_ops["Deployment / runtime"]
  node_vercel_host{{"Vercel<br/>hosting<br/>[vercel.json]"}}
  node_redirects["Redirect rules<br/>routing"]
  node_vite_tooling["Vite build<br/>dev tooling<br/>[vite.config.js]"]
  node_local_server["Local server<br/>runtime<br/>[server.js]"]
end

node_index_page -->|"entry"| node_login_page
node_login_page -->|"loads"| node_auth_js
node_user_page -->|"loads"| node_user_js
node_admin_page -->|"loads"| node_admin_js
node_login_page -->|"styles"| node_shared_css
node_user_page -->|"styles"| node_shared_css
node_admin_page -->|"styles"| node_shared_css
node_auth_js -->|"uses"| node_firebase_cfg
node_user_js -->|"uses"| node_firebase_cfg
node_admin_js -->|"uses"| node_firebase_cfg
node_auth_js -->|"sign-in"| node_firebase_service
node_user_js -->|"session check"| node_firebase_service
node_admin_js -->|"gate access"| node_firebase_service
node_admin_js -->|"admin actions"| node_manage_user_api
node_admin_js -->|"send mail"| node_welcome_api
node_welcome_api -->|"renders"| node_email_template
node_welcome_api -->|"delivers"| node_email_service
node_manage_user_api -->|"reads/writes"| node_supabase_service
node_manage_user_api -.->|"notifies"| node_email_service
node_vercel_host -->|"routes"| node_redirects
node_vercel_host -->|"hosts"| node_welcome_api
node_vercel_host -->|"hosts"| node_manage_user_api
node_vite_tooling -.->|"builds"| node_login_page
node_vite_tooling -.->|"builds"| node_user_page
node_vite_tooling -.->|"builds"| node_admin_page
node_local_server -.->|"serves"| node_login_page
node_local_server -.->|"serves"| node_user_page
node_local_server -.->|"serves"| node_admin_page
node_local_server -.->|"runs"| node_welcome_api
node_local_server -.->|"runs"| node_manage_user_api

click node_index_page "https://github.com/zamtls15/googlehelportal-v1/blob/main/index.html"
click node_login_page "https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/login.html"
click node_user_page "https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/user.html"
click node_admin_page "https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/hq-control-7x9k.html"
click node_shared_css "https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/shared.css"
click node_auth_js "https://github.com/zamtls15/googlehelportal-v1/blob/main/js/auth.js"
click node_user_js "https://github.com/zamtls15/googlehelportal-v1/blob/main/js/user.js"
click node_admin_js "https://github.com/zamtls15/googlehelportal-v1/blob/main/js/admin.js"
click node_firebase_cfg "https://github.com/zamtls15/googlehelportal-v1/blob/main/js/firebase-config.js"
click node_welcome_api "https://github.com/zamtls15/googlehelportal-v1/blob/main/api/send-welcome-email/index.js"
click node_manage_user_api "https://github.com/zamtls15/googlehelportal-v1/blob/main/api/manage-supabase-user/index.js"
click node_email_template "https://github.com/zamtls15/googlehelportal-v1/blob/main/api/email-template.js"
click node_vercel_host "https://github.com/zamtls15/googlehelportal-v1/blob/main/vercel.json"
click node_redirects "https://github.com/zamtls15/googlehelportal-v1/tree/main/public/_redirects"
click node_vite_tooling "https://github.com/zamtls15/googlehelportal-v1/blob/main/vite.config.js"
click node_local_server "https://github.com/zamtls15/googlehelportal-v1/blob/main/server.js"

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_page,node_login_page,node_user_page,node_admin_page,node_shared_css,node_auth_js,node_user_js,node_admin_js,node_firebase_cfg toneBlue
class node_welcome_api,node_manage_user_api,node_email_template toneAmber
class node_firebase_service,node_supabase_service,node_email_service toneMint
class node_vercel_host,node_redirects,node_vite_tooling,node_local_server toneRose
```

## Components

### Browser app

Static pages and client-side modules

- [Landing](https://github.com/zamtls15/googlehelportal-v1/blob/main/index.html): static page · Root entry page for the portal · `index.html`
- [Login](https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/login.html): static page · Email-based sign-in surface · `pages/login.html`
- [Member portal](https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/user.html): static page · Authenticated member experience · `pages/user.html`
- [Control room](https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/hq-control-7x9k.html): static page · Obscure admin/control surface · `pages/hq-control-7x9k.html`
- [Shared CSS](https://github.com/zamtls15/googlehelportal-v1/blob/main/pages/shared.css): styles · Common presentation layer for page surfaces · `pages/shared.css`
- [Auth flow](https://github.com/zamtls15/googlehelportal-v1/blob/main/js/auth.js): client module · Sign-in and session handling · `js/auth.js`
- [Member UI](https://github.com/zamtls15/googlehelportal-v1/blob/main/js/user.js): client module · Drives the member dashboard behavior · `js/user.js`
- [Admin UI](https://github.com/zamtls15/googlehelportal-v1/blob/main/js/admin.js): client module · Drives the admin/control panel · `js/admin.js`
- [Firebase config](https://github.com/zamtls15/googlehelportal-v1/blob/main/js/firebase-config.js): client config · Shared client-side Firebase setup · `js/firebase-config.js`

### Serverless API

Privileged backend functions and shared email content

- [Welcome email](https://github.com/zamtls15/googlehelportal-v1/blob/main/api/send-welcome-email/index.js): serverless fn · Sends onboarding and welcome mail · `api/send-welcome-email/index.js`
- [User manager](https://github.com/zamtls15/googlehelportal-v1/blob/main/api/manage-supabase-user/index.js): serverless fn · Privileged member create/update operations · `api/manage-supabase-user/index.js`
- [Email template](https://github.com/zamtls15/googlehelportal-v1/blob/main/api/email-template.js): shared mail · Reusable email markup and content · `api/email-template.js`

### External services

Third-party systems used by auth, data, and email delivery

- **Firebase**: auth service · External authentication provider
- **Supabase**: data service · Backend store for member and admin records
- **Email delivery**: mail provider · Outbound email infrastructure

### Deployment / runtime

Hosting, routing, and local dev tooling

- [Vercel](https://github.com/zamtls15/googlehelportal-v1/blob/main/vercel.json): hosting · Static hosting and serverless deployment target · `vercel.json`
- [Redirect rules](https://github.com/zamtls15/googlehelportal-v1/tree/main/public/_redirects): routing · Edge routing and fallback handling · `public/_redirects`
- [Vite build](https://github.com/zamtls15/googlehelportal-v1/blob/main/vite.config.js): dev tooling · Local dev and bundling setup · `vite.config.js`
- [Local server](https://github.com/zamtls15/googlehelportal-v1/blob/main/server.js): runtime · Alternative local runtime entry · `server.js`

## Connections

- Landing → Login: entry · Landing routes into sign-in
- Login → Auth flow: loads · Login page uses auth module
- Member portal → Member UI: loads · Member page uses dashboard logic
- Control room → Admin UI: loads · Admin page uses control logic
- Login → Shared CSS: styles · Shared styling across page surfaces
- Member portal → Shared CSS: styles · Shared styling across page surfaces
- Control room → Shared CSS: styles · Shared styling across page surfaces
- Auth flow → Firebase config: uses · Auth logic relies on shared Firebase setup
- Member UI → Firebase config: uses · Member UI consumes the same client config
- Admin UI → Firebase config: uses · Admin UI consumes the same client config
- Auth flow → Firebase: sign-in · Email-based authentication flow
- Member UI → Firebase: session check · Reads authenticated member state
- Admin UI → Firebase: gate access · Checks privileged access before actions
- Admin UI → User manager: admin actions · Creates or updates member records
- Admin UI → Welcome email: send mail · Triggers onboarding email delivery
- Welcome email → Email template: renders · Builds outgoing email content
- Welcome email → Email delivery: delivers · Sends welcome mail externally
- User manager → Supabase: reads/writes · Manages member records in Supabase
- User manager → Email delivery: notifies · May trigger notification mail as part of admin flows
- Vercel → Redirect rules: routes · Edge routing and fallback handling
- Vercel → Welcome email: hosts · Deploys serverless API function
- Vercel → User manager: hosts · Deploys serverless API function
- Vite build → Login: builds · Development build tooling covers static pages
- Vite build → Member portal: builds · Development build tooling covers static pages
- Vite build → Control room: builds · Development build tooling covers static pages
- Local server → Login: serves · Local runtime support for pages
- Local server → Member portal: serves · Local runtime support for pages
- Local server → Control room: serves · Local runtime support for pages
- Local server → Welcome email: runs · Local runtime can invoke API functions
- Local server → User manager: runs · Local runtime can invoke API functions
