# stephenwu433/planflow-app architecture

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

- Interactive diagram: https://gitdiagram.com/stephenwu433/planflow-app
- Repository: https://github.com/stephenwu433/planflow-app

## Overview

PlanFlow is a team project-portfolio and scheduling product with a Next.js interface, FastAPI API, Neon-backed persistence, and Clerk authentication. The principal workflow is to join or create a team, create and schedule projects, manage project tasks, and record daily progress and hours; team and portfolio views surface that work across projects. The tree documents additional schedule, workload, reporting, and notification capabilities. Some routes and API helpers were not sampled, so their links are shown only where filenames and documented product structure support them.

Main entry points: [`backend/app/main.py`](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/main.py) (FastAPI entry), [`planflow/lib/api-client.ts`](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/api-client.ts) (HTTP client), [`backend/app/db.py`](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/db.py) (Database access), [`planflow/app/teams/[teamId]/projects/[projectId]/page.tsx`](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/teams/%5BteamId%5D/projects/%5BprojectId%5D/page.tsx) (Project workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_team_pages["Teams and projects<br/>[page.tsx]"]
  node_shell["Workbench shell<br/>[WorkbenchShell.tsx]"]
  node_portfolio_page["Portfolio<br/>[page.tsx]"]
  node_project_pages["Project workspace<br/>[page.tsx]"]
  node_daily_pages["Daily work views<br/>[page.tsx]"]
  node_teamday_page["Team day<br/>[page.tsx]"]
  node_workload_page["Workload view<br/>[page.tsx]"]
end

subgraph group_client["API client"]
  node_api_client["HTTP client<br/>[api-client.ts]"]
  node_team_project_api["Team and project APIs<br/>[projects-api.ts]"]
  node_task_api["Task APIs<br/>[tasks-api.ts]"]
  node_daily_api["Daily work APIs<br/>[daily-tasks-api.ts]"]
  node_teamdaily_api["Team daily API<br/>[team-daily-api.ts]"]
  node_workload_api["Workload API<br/>[workload-api.ts]"]
  node_specialized_api["Schedule and reports"]
  node_notifications_api["Notifications API"]
end

subgraph group_backend["API services"]
  node_app["FastAPI entry<br/>[main.py]"]
  node_teams_router["Teams and projects<br/>[teams.py]"]
  node_tasks_router["Project tasks<br/>[tasks.py]"]
  node_daily_router["Daily tasks and time<br/>[daily_tasks.py]"]
  node_daily_views_router["Daily and workload views<br/>[team_daily.py]"]
  node_schedule_router["Schedules and reports<br/>[cycle_schedule.py]"]
  node_notifications_router["Notifications<br/>[notifications.py]"]
end

subgraph group_identity["Identity and storage"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_db["Database access<br/>[db.py]"]
end

node_team_user(("Team user"))
node_neon[("Neon PostgreSQL")]
node_clerk["Clerk identity"]

node_team_user -->|"manages teams"| node_team_pages
node_team_user -->|"views portfolio"| node_portfolio_page
node_team_user -->|"works on projects"| node_project_pages
node_team_user -->|"records progress"| node_daily_pages
node_team_user -->|"reviews team"| node_teamday_page
node_team_user -->|"reviews workload"| node_workload_page
node_team_pages -->|"creates and schedules"| node_team_project_api
node_shell -->|"loads portfolio"| node_team_project_api
node_portfolio_page -->|"loads projects"| node_team_project_api
node_project_pages -->|"manages tasks"| node_task_api
node_daily_pages -->|"logs hours"| node_daily_api
node_daily_pages -->|"updates status"| node_task_api
node_teamday_page -->|"loads team board"| node_teamdaily_api
node_workload_page -->|"loads workload"| node_workload_api
node_project_pages -->|"uses schedules and reports"| node_specialized_api
node_project_pages -.->|"views notifications"| node_notifications_api
node_team_project_api -->|"sends requests"| node_api_client
node_task_api -->|"sends requests"| node_api_client
node_daily_api -->|"sends requests"| node_api_client
node_teamdaily_api -->|"sends requests"| node_api_client
node_workload_api -->|"sends requests"| node_api_client
node_specialized_api -->|"sends requests"| node_api_client
node_notifications_api -->|"sends requests"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"dispatches routes"| node_teams_router
node_app -->|"dispatches routes"| node_tasks_router
node_app -->|"dispatches routes"| node_daily_router
node_app -->|"dispatches routes"| node_daily_views_router
node_app -->|"dispatches routes"| node_schedule_router
node_app -->|"dispatches routes"| node_notifications_router
node_app -->|"authenticates requests"| node_auth
node_auth -->|"verifies JWT"| node_clerk
node_teams_router -->|"reads and writes"| node_db
node_tasks_router -->|"reads and writes"| node_db
node_daily_router -->|"reads and writes"| node_db
node_daily_views_router -->|"reads data"| node_db
node_schedule_router -->|"reads and writes"| node_db
node_notifications_router -->|"reads and writes"| node_db
node_db -->|"queries"| node_neon

click node_team_pages "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/teams/%5BteamId%5D/page.tsx"
click node_shell "https://github.com/stephenwu433/planflow-app/blob/main/planflow/components/WorkbenchShell.tsx"
click node_portfolio_page "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/portfolio/page.tsx"
click node_project_pages "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/teams/%5BteamId%5D/projects/%5BprojectId%5D/page.tsx"
click node_daily_pages "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/my-day/page.tsx"
click node_teamday_page "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/team-day/page.tsx"
click node_workload_page "https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/workload/page.tsx"
click node_api_client "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/api-client.ts"
click node_team_project_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/projects-api.ts"
click node_task_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/tasks-api.ts"
click node_daily_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/daily-tasks-api.ts"
click node_teamdaily_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/team-daily-api.ts"
click node_workload_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/workload-api.ts"
click node_specialized_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/cycle-schedule-api.ts"
click node_notifications_api "https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/notifications-api.ts"
click node_app "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/main.py"
click node_teams_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/teams.py"
click node_tasks_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/tasks.py"
click node_daily_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/daily_tasks.py"
click node_daily_views_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/team_daily.py"
click node_schedule_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/cycle_schedule.py"
click node_notifications_router "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/notifications.py"
click node_auth "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/auth.py"
click node_db "https://github.com/stephenwu433/planflow-app/blob/main/backend/app/db.py"

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_team_pages,node_shell,node_portfolio_page,node_project_pages,node_daily_pages,node_teamday_page,node_workload_page,node_team_user toneBlue
class node_api_client,node_team_project_api,node_task_api,node_daily_api,node_teamdaily_api,node_workload_api,node_specialized_api,node_notifications_api,node_neon toneAmber
class node_app,node_teams_router,node_tasks_router,node_daily_router,node_daily_views_router,node_schedule_router,node_notifications_router toneMint
class node_auth,node_db toneRose
class node_clerk toneIndigo
```

## Components

### Web interface

- [Teams and projects](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/teams/%5BteamId%5D/page.tsx): `planflow/app/teams/[teamId]/page.tsx`
- [Workbench shell](https://github.com/stephenwu433/planflow-app/blob/main/planflow/components/WorkbenchShell.tsx): `planflow/components/WorkbenchShell.tsx`
- [Portfolio](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/portfolio/page.tsx): `planflow/app/portfolio/page.tsx`
- [Project workspace](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/teams/%5BteamId%5D/projects/%5BprojectId%5D/page.tsx): `planflow/app/teams/[teamId]/projects/[projectId]/page.tsx`
- [Daily work views](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/my-day/page.tsx): `planflow/app/my-day/page.tsx`
- [Team day](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/team-day/page.tsx): `planflow/app/team-day/page.tsx`
- [Workload view](https://github.com/stephenwu433/planflow-app/blob/main/planflow/app/workload/page.tsx): `planflow/app/workload/page.tsx`

### API client

- [HTTP client](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/api-client.ts): `planflow/lib/api-client.ts`
- [Team and project APIs](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/projects-api.ts): `planflow/lib/projects-api.ts`
- [Task APIs](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/tasks-api.ts): `planflow/lib/tasks-api.ts`
- [Daily work APIs](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/daily-tasks-api.ts): `planflow/lib/daily-tasks-api.ts`
- [Team daily API](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/team-daily-api.ts): `planflow/lib/team-daily-api.ts`
- [Workload API](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/workload-api.ts): `planflow/lib/workload-api.ts`
- [Schedule and reports](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/cycle-schedule-api.ts): `planflow/lib/cycle-schedule-api.ts`
- [Notifications API](https://github.com/stephenwu433/planflow-app/blob/main/planflow/lib/notifications-api.ts): `planflow/lib/notifications-api.ts`

### API services

- [FastAPI entry](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/main.py): `backend/app/main.py`
- [Teams and projects](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/teams.py): `backend/app/routers/teams.py`
- [Project tasks](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/tasks.py): `backend/app/routers/tasks.py`
- [Daily tasks and time](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/daily_tasks.py): `backend/app/routers/daily_tasks.py`
- [Daily and workload views](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/team_daily.py): `backend/app/routers/team_daily.py`
- [Schedules and reports](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/cycle_schedule.py): `backend/app/routers/cycle_schedule.py`
- [Notifications](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/routers/notifications.py): `backend/app/routers/notifications.py`

### Identity and storage

- [JWT authentication](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Database access](https://github.com/stephenwu433/planflow-app/blob/main/backend/app/db.py): `backend/app/db.py`

### Other components

- **Team user**
- **Neon PostgreSQL**
- **Clerk identity**

## Connections

- Team user → Teams and projects: manages teams
- Team user → Portfolio: views portfolio
- Team user → Project workspace: works on projects
- Team user → Daily work views: records progress
- Team user → Team day: reviews team
- Team user → Workload view: reviews workload
- Teams and projects → Team and project APIs: creates and schedules
- Workbench shell → Team and project APIs: loads portfolio
- Portfolio → Team and project APIs: loads projects
- Project workspace → Task APIs: manages tasks
- Daily work views → Daily work APIs: logs hours
- Daily work views → Task APIs: updates status
- Team day → Team daily API: loads team board
- Workload view → Workload API: loads workload
- Project workspace → Schedule and reports: uses schedules and reports
- Project workspace → Notifications API: views notifications
- Team and project APIs → HTTP client: sends requests
- Task APIs → HTTP client: sends requests
- Daily work APIs → HTTP client: sends requests
- Team daily API → HTTP client: sends requests
- Workload API → HTTP client: sends requests
- Schedule and reports → HTTP client: sends requests
- Notifications API → HTTP client: sends requests
- HTTP client → FastAPI entry: calls API
- FastAPI entry → Teams and projects: dispatches routes
- FastAPI entry → Project tasks: dispatches routes
- FastAPI entry → Daily tasks and time: dispatches routes
- FastAPI entry → Daily and workload views: dispatches routes
- FastAPI entry → Schedules and reports: dispatches routes
- FastAPI entry → Notifications: dispatches routes
- FastAPI entry → JWT authentication: authenticates requests
- JWT authentication → Clerk identity: verifies JWT
- Teams and projects → Database access: reads and writes
- Project tasks → Database access: reads and writes
- Daily tasks and time → Database access: reads and writes
- Daily and workload views → Database access: reads data
- Schedules and reports → Database access: reads and writes
- Notifications → Database access: reads and writes
- Database access → Neon PostgreSQL: queries