# nkminion/flowstate architecture

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

- Interactive diagram: https://gitdiagram.com/nkminion/flowstate
- Repository: https://github.com/nkminion/flowstate

## Overview

FlowState is a collaborative workspace and Kanban-style board app. Users sign in with Google or GitHub, enter workspaces, manage boards, and organize cards into ordered lists; board membership and roles govern collaboration. The web pages call an Express API, which uses PostgreSQL for application data and sessions for selected workspace/board context. Separate user-facing capabilities include inbox notifications and workspace activity history. The source excerpts show the API and several UI requests, but not the full schema or all handlers, so some subsystem relationships are documented only at the UI boundary.

Main entry points: [`Server/index.js`](https://github.com/nkminion/flowstate/blob/main/Server/index.js) (Express API), [`Server/src/config/db.js`](https://github.com/nkminion/flowstate/blob/main/Server/src/config/db.js) (Database access), [`Server/server.js`](https://github.com/nkminion/flowstate/blob/main/Server/server.js) (Page serving), [`public/login_script.js`](https://github.com/nkminion/flowstate/blob/main/public/login_script.js) (Sign-in page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_pages["Page serving<br/>[server.js]"]
  node_login["Sign-in page<br/>[login_script.js]"]
  node_home["Workspace home<br/>[home_script.js]"]
  node_workspace_ui["Workspace page"]
  node_boards_ui["Board page<br/>[boards_script.js]"]
  node_inbox_ui["Inbox page<br/>[inbox_script.js]"]
  node_history_ui["History page<br/>[history_script.js]"]
end

subgraph group_api["API and identity"]
  node_api["Express API<br/>[index.js]"]
  node_oauth["OAuth providers"]
  node_session[("Session context<br/>[index.js]")]
  node_dbclient["Database access<br/>[db.js]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_collab["Workspace collaboration"]
  node_workspace_ops["Workspace management<br/>[index.js]"]
  node_membership["Workspace membership<br/>[index.js]"]
end

subgraph group_board["Board workflow"]
  node_board_ops["Board management<br/>[index.js]"]
  node_lists_cards["Lists and cards<br/>[index.js]"]
  node_board_members["Board roles<br/>[index.js]"]
end

subgraph group_records["User records"]
  node_notifications["Inbox notifications<br/>[index.js]"]
  node_activity["Workspace history<br/>[index.js]"]
end

node_visitor(("User"))

node_visitor -->|"opens pages"| node_pages
node_pages -->|"serves login"| node_login
node_pages -->|"serves home"| node_home
node_pages -->|"serves workspace"| node_workspace_ui
node_pages -->|"serves board"| node_boards_ui
node_login -->|"starts sign-in"| node_api
node_api -->|"authenticates with"| node_oauth
node_home -->|"requests workspaces"| node_api
node_workspace_ui -->|"manages boards"| node_api
node_boards_ui -->|"manages board"| node_api
node_inbox_ui -->|"loads notifications"| node_api
node_history_ui -->|"loads history"| node_api
node_api -->|"reads context"| node_session
node_api -->|"queries data"| node_dbclient
node_dbclient -->|"executes queries"| node_postgres
node_api -->|"handles requests"| node_workspace_ops
node_api -->|"handles requests"| node_membership
node_api -->|"handles requests"| node_board_ops
node_api -->|"handles requests"| node_lists_cards
node_api -->|"handles requests"| node_board_members
node_api -->|"handles requests"| node_notifications
node_api -->|"handles requests"| node_activity
node_workspace_ops -.->|"queries data"| node_dbclient
node_membership -.->|"queries data"| node_dbclient
node_board_ops -.->|"queries data"| node_dbclient
node_lists_cards -->|"queries data"| node_dbclient
node_board_members -.->|"queries data"| node_dbclient
node_notifications -->|"queries data"| node_dbclient
node_activity -->|"queries data"| node_dbclient

click node_pages "https://github.com/nkminion/flowstate/blob/main/Server/server.js"
click node_login "https://github.com/nkminion/flowstate/blob/main/public/login_script.js"
click node_home "https://github.com/nkminion/flowstate/blob/main/public/home_script.js"
click node_workspace_ui "https://github.com/nkminion/flowstate/blob/main/public/workspace_script.js"
click node_boards_ui "https://github.com/nkminion/flowstate/blob/main/public/boards_script.js"
click node_inbox_ui "https://github.com/nkminion/flowstate/blob/main/public/inbox_script.js"
click node_history_ui "https://github.com/nkminion/flowstate/blob/main/public/history_script.js"
click node_api "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_session "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_dbclient "https://github.com/nkminion/flowstate/blob/main/Server/src/config/db.js"
click node_workspace_ops "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_membership "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_board_ops "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_lists_cards "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_board_members "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_notifications "https://github.com/nkminion/flowstate/blob/main/Server/index.js"
click node_activity "https://github.com/nkminion/flowstate/blob/main/Server/index.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_pages,node_login,node_home,node_workspace_ui,node_boards_ui,node_inbox_ui,node_history_ui,node_visitor toneBlue
class node_api,node_oauth,node_session,node_dbclient,node_postgres toneAmber
class node_workspace_ops,node_membership toneMint
class node_board_ops,node_lists_cards,node_board_members toneRose
class node_notifications,node_activity toneIndigo
```

## Components

### Web interface

- [Page serving](https://github.com/nkminion/flowstate/blob/main/Server/server.js): `Server/server.js`
- [Sign-in page](https://github.com/nkminion/flowstate/blob/main/public/login_script.js): `public/login_script.js`
- [Workspace home](https://github.com/nkminion/flowstate/blob/main/public/home_script.js): `public/home_script.js`
- [Workspace page](https://github.com/nkminion/flowstate/blob/main/public/workspace_script.js): `public/workspace_script.js`
- [Board page](https://github.com/nkminion/flowstate/blob/main/public/boards_script.js): `public/boards_script.js`
- [Inbox page](https://github.com/nkminion/flowstate/blob/main/public/inbox_script.js): `public/inbox_script.js`
- [History page](https://github.com/nkminion/flowstate/blob/main/public/history_script.js): `public/history_script.js`

### API and identity

- [Express API](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- **OAuth providers**
- [Session context](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- [Database access](https://github.com/nkminion/flowstate/blob/main/Server/src/config/db.js): `Server/src/config/db.js`
- **PostgreSQL**

### Workspace collaboration

- [Workspace management](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- [Workspace membership](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`

### Board workflow

- [Board management](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- [Lists and cards](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- [Board roles](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`

### User records

- [Inbox notifications](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`
- [Workspace history](https://github.com/nkminion/flowstate/blob/main/Server/index.js): `Server/index.js`

### Other components

- **User**

## Connections

- User → Page serving: opens pages (evidence: `Server/server.js`)
- Page serving → Sign-in page: serves login (evidence: `Server/server.js`)
- Page serving → Workspace home: serves home (evidence: `Server/server.js`)
- Page serving → Workspace page: serves workspace (evidence: `Server/server.js`)
- Page serving → Board page: serves board (evidence: `Server/server.js`)
- Sign-in page → Express API: starts sign-in (evidence: `public/login_script.js`)
- Express API → OAuth providers: authenticates with (evidence: `Server/index.js`)
- Workspace home → Express API: requests workspaces (evidence: `public/home_script.js`)
- Workspace page → Express API: manages boards (evidence: `public/workspace_script.js`)
- Board page → Express API: manages board (evidence: `public/boards_script.js`)
- Inbox page → Express API: loads notifications (evidence: `public/inbox_script.js`)
- History page → Express API: loads history (evidence: `public/history_script.js`)
- Express API → Session context: reads context (evidence: `Server/index.js`)
- Express API → Database access: queries data (evidence: `Server/index.js`)
- Database access → PostgreSQL: executes queries (evidence: `Server/src/config/db.js`)
- Express API → Workspace management: handles requests (evidence: `Server/index.js`)
- Express API → Workspace membership: handles requests (evidence: `Server/index.js`)
- Express API → Board management: handles requests (evidence: `Server/index.js`)
- Express API → Lists and cards: handles requests (evidence: `Server/index.js`)
- Express API → Board roles: handles requests (evidence: `Server/index.js`)
- Express API → Inbox notifications: handles requests (evidence: `Server/index.js`)
- Express API → Workspace history: handles requests (evidence: `Server/index.js`)
- Workspace management → Database access: queries data (evidence: `Server/index.js`)
- Workspace membership → Database access: queries data (evidence: `Server/index.js`)
- Board management → Database access: queries data (evidence: `Server/index.js`)
- Lists and cards → Database access: queries data (evidence: `Server/index.js`)
- Board roles → Database access: queries data (evidence: `Server/index.js`)
- Inbox notifications → Database access: queries data (evidence: `Server/index.js`)
- Workspace history → Database access: queries data (evidence: `Server/index.js`)
