# afloresc/pm_flow_dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/afloresc/pm_flow_dashboard
- Repository: https://github.com/afloresc/pm_flow_dashboard

## Overview

#### Purpose and Entry Points
PRO-FLOW is a single-page enterprise project-management dashboard for task execution, timelines, resource capacity, reporting, and AI-assisted audits. The browser enters through `index.html` and mounts React in `src/main.tsx`; `src/App.tsx` owns the authenticated application shell and workspace/view selection. `server.ts` is the Node/Express runtime entry point for development middleware, production static hosting, and backend API routes.

#### Authentication and Role Boundary
`src/components/AuthScreen.tsx` provides Firebase-backed sign-up/sign-in plus local demo sessions. Firebase mode delegates identity to Firebase Authentication and persists user roles in Firestore; demo mode stores a mock session in browser local storage. The app uses shared domain and role definitions from `src/types.ts`, allowing manager/member permissions to gate editing and allocation-oriented actions.

#### Project Data Synchronization
`src/hooks/useProjectData.ts` is the client data boundary and synchronization engine. It reads and writes project entities—including tasks, subtasks, resource allocations, logs, and comments—against Cloud Firestore for live collaboration, while providing LocalStorage fallback behavior when cloud access is unavailable. `src/firebase.ts` initializes the Firebase Auth and Firestore SDK clients used by this layer.

#### Workspace Modules
`src/App.tsx` composes the major operational views:
- `src/components/TaskTracking.tsx`: task CRUD, checklists, progress, logs, and discussion activity.
- `src/components/GanttChart.tsx`: expected-versus-actual schedule visualization and task navigation.
- `src/components/ResourceAllocation.tsx`: personnel/material registry, costs, assignments, and workload/overload indicators.
- `src/components/AutomatedReporting.tsx`: project exports, AI audit invocation, and AI-report export.

These components consume the shared project state rather than directly defining persistence infrastructure.

#### AI Audit Server Boundary
Gemini access is intentionally server-side: `src/components/AutomatedReporting.tsx` submits project/audit context to API routes exposed by `server.ts`. The Express layer uses the Gemini SDK and `GEMINI_API_KEY` environment secret, preventing that credential from reaching the browser. Returned audit results identify schedule risks, bottlenecks, cost variance, and potential resource reallocation; the client displays and exports the resulting report.

#### Runtime and Deployment Infrastructure
The frontend runs on React 19, TypeScript, Vite, MUI, Tailwind, Motion, and Lucide. `vite.config.ts` configures the frontend build; `server.ts` serves Vite during development and built static assets in production. Firebase deployment/project configuration and data-access policy are represented by `firebase.json`, `firebase-blueprint.json`, and `firestore.rules`. Node.js 18+ is the material runtime; Firebase Authentication, Cloud Firestore, and Gemini are the external managed services.

#### Security and Persistence Boundaries
Browser code may access Firebase through `src/firebase.ts` under Firestore rules in `firestore.rules`; durable authorization must therefore be enforced by Firebase policies rather than UI role checks alone. Server-only Gemini credentials belong in environment configuration (`.env.example`) and are mediated by `server.ts`. LocalStorage is a resilience/demo store, not an authoritative collaborative data source.

Main entry points: [`src/App.tsx`](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/App.tsx) (App shell), [`src/components/AuthScreen.tsx`](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/AuthScreen.tsx) (Auth screen), [`src/firebase.ts`](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/firebase.ts) (Firebase client), [`server.ts`](https://github.com/afloresc/pm_flow_dashboard/blob/main/server.ts) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_html["HTML entry<br/>entrypoint<br/>[index.html]"]
  node_main["React mount<br/>bootstrap<br/>[main.tsx]"]
  node_app["App shell<br/>workspace shell<br/>[App.tsx]"]
  node_auth["Auth screen<br/>authentication UI<br/>[AuthScreen.tsx]"]
  node_types["Domain roles<br/>shared types<br/>[types.ts]"]
  node_project_data{{"Project sync<br/>data boundary<br/>[useProjectData.ts]"}}
  node_firebase_client["Firebase client<br/>SDK initialization<br/>[firebase.ts]"]
  node_task_tracking["Task tracking<br/>workspace module<br/>[TaskTracking.tsx]"]
  node_gantt["Gantt chart<br/>workspace module<br/>[GanttChart.tsx]"]
  node_resources["Resource allocation<br/>workspace module"]
  node_reporting["Automated reporting<br/>workspace module"]
  node_local_storage[("LocalStorage<br/>fallback store")]
end

subgraph group_server["Node server"]
  node_server_entry["Express server<br/>runtime entrypoint<br/>[server.ts]"]
  node_vite["Vite build<br/>frontend build config<br/>[vite.config.ts]"]
  node_gemini_secret["Gemini API key<br/>server environment secret<br/>[.env.example]"]
end

subgraph group_managed["Managed services"]
  node_firebase_auth(("Firebase Auth<br/>identity service"))
  node_firestore[("Cloud Firestore<br/>collaborative datastore")]
  node_firestore_rules["Firestore rules<br/>authorization policy<br/>[firestore.rules]"]
  node_gemini(("Gemini API<br/>AI audit service"))
end

node_html -->|"loads"| node_main
node_main -->|"mounts"| node_app
node_app -->|"authenticates through"| node_auth
node_app -->|"uses shared state"| node_project_data
node_app -->|"composes"| node_task_tracking
node_app -->|"composes"| node_gantt
node_app -->|"composes"| node_resources
node_app -->|"composes"| node_reporting
node_auth -->|"uses roles"| node_types
node_auth -->|"uses"| node_firebase_client
node_auth -.->|"demo session"| node_local_storage
node_project_data -->|"uses"| node_firebase_client
node_project_data -.->|"fallback"| node_local_storage
node_firebase_client -->|"authenticates with"| node_firebase_auth
node_firebase_client -->|"reads and writes"| node_firestore
node_firestore_rules -->|"authorizes access"| node_firestore
node_reporting -->|"AI audit API"| node_server_entry
node_server_entry -->|"invokes audit"| node_gemini
node_gemini_secret -.->|"configures"| node_server_entry
node_vite -.->|"development middleware"| node_server_entry

click node_html "https://github.com/afloresc/pm_flow_dashboard/blob/main/index.html"
click node_main "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/main.tsx"
click node_app "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/App.tsx"
click node_auth "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/AuthScreen.tsx"
click node_types "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/types.ts"
click node_project_data "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/hooks/useProjectData.ts"
click node_firebase_client "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/firebase.ts"
click node_task_tracking "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/TaskTracking.tsx"
click node_gantt "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/GanttChart.tsx"
click node_resources "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/ResourceAllocation.tsx"
click node_reporting "https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/AutomatedReporting.tsx"
click node_server_entry "https://github.com/afloresc/pm_flow_dashboard/blob/main/server.ts"
click node_vite "https://github.com/afloresc/pm_flow_dashboard/blob/main/vite.config.ts"
click node_firestore_rules "https://github.com/afloresc/pm_flow_dashboard/blob/main/firestore.rules"
click node_gemini_secret "https://github.com/afloresc/pm_flow_dashboard/blob/main/.env.example"

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_html,node_main,node_app,node_auth,node_types,node_project_data,node_firebase_client,node_task_tracking,node_gantt,node_resources,node_reporting,node_local_storage toneBlue
class node_server_entry,node_vite,node_gemini_secret toneAmber
class node_firebase_auth,node_firestore,node_firestore_rules,node_gemini toneMint
```

## Components

### Browser app

React dashboard and client data boundary.

- [HTML entry](https://github.com/afloresc/pm_flow_dashboard/blob/main/index.html): entrypoint · `index.html`
- [React mount](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/main.tsx): bootstrap · `src/main.tsx`
- [App shell](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/App.tsx): workspace shell · Owns authenticated workspace and view selection. · `src/App.tsx`
- [Auth screen](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/AuthScreen.tsx): authentication UI · Supports Firebase identities and local demo sessions. · `src/components/AuthScreen.tsx`
- [Domain roles](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/types.ts): shared types · Manager/member permissions gate client actions. · `src/types.ts`
- [Project sync](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/hooks/useProjectData.ts): data boundary · Synchronizes project entities with cloud storage or local fallback. · `src/hooks/useProjectData.ts`
- [Firebase client](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/firebase.ts): SDK initialization · `src/firebase.ts`
- [Task tracking](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/TaskTracking.tsx): workspace module · Tasks, checklists, progress, logs, and comments. · `src/components/TaskTracking.tsx`
- [Gantt chart](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/GanttChart.tsx): workspace module · Expected-versus-actual schedule view. · `src/components/GanttChart.tsx`
- [Resource allocation](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/ResourceAllocation.tsx): workspace module · Assignments, costs, and workload indicators. · `src/components/ResourceAllocation.tsx`
- [Automated reporting](https://github.com/afloresc/pm_flow_dashboard/blob/main/src/components/AutomatedReporting.tsx): workspace module · Exports projects and invokes AI audits. · `src/components/AutomatedReporting.tsx`
- **LocalStorage**: fallback store · Resilience and demo storage, not collaborative authority.

### Node server

Hosting and server-side AI boundary.

- [Express server](https://github.com/afloresc/pm_flow_dashboard/blob/main/server.ts): runtime entrypoint · Serves Vite/static assets and exposes backend API routes. · `server.ts`
- [Vite build](https://github.com/afloresc/pm_flow_dashboard/blob/main/vite.config.ts): frontend build config · `vite.config.ts`
- [Gemini API key](https://github.com/afloresc/pm_flow_dashboard/blob/main/.env.example): server environment secret · Kept out of browser code. · `.env.example`

### Managed services

Firebase and Gemini services.

- **Firebase Auth**: identity service
- **Cloud Firestore**: collaborative datastore · Live project data and user roles.
- [Firestore rules](https://github.com/afloresc/pm_flow_dashboard/blob/main/firestore.rules): authorization policy · Enforces durable browser data access authorization. · `firestore.rules`
- **Gemini API**: AI audit service · Receives server-mediated audit requests.

## Connections

- HTML entry → React mount: loads
- React mount → App shell: mounts
- App shell → Auth screen: authenticates through
- App shell → Project sync: uses shared state
- App shell → Task tracking: composes
- App shell → Gantt chart: composes
- App shell → Resource allocation: composes
- App shell → Automated reporting: composes
- Auth screen → Domain roles: uses roles
- Auth screen → Firebase client: uses
- Auth screen → LocalStorage: demo session
- Project sync → Firebase client: uses
- Project sync → LocalStorage: fallback
- Firebase client → Firebase Auth: authenticates with
- Firebase client → Cloud Firestore: reads and writes
- Firestore rules → Cloud Firestore: authorizes access
- Automated reporting → Express server: AI audit API
- Express server → Gemini API: invokes audit
- Gemini API key → Express server: configures
- Vite build → Express server: development middleware