# drawleados-dotcom/drawleados architecture

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

- Interactive diagram: https://gitdiagram.com/drawleados-dotcom/drawleados
- Repository: https://github.com/drawleados-dotcom/drawleados

## Overview

#### Purpose and Shape
Drawlead is a full-stack internal business-management platform spanning CRM/leads, operations/projects/tasks, HR/payroll, finance/invoicing, marketing, documentation, BNI workflows, and client portals. The repository contains a React single-page frontend, a Python API backend, MongoDB backup data, and containerized deployment assets.

#### Entry Points and Delivery
The browser application starts at `frontend/src/index.js` and composes routing/application state in `frontend/src/App.js`. The backend API process is centralized in `backend/server.py`, which integrates the domain route modules. Production deployment is Docker Compose behind Nginx: `deploy/docker-compose.yml`, `deploy/nginx.conf`, `deploy/backend.Dockerfile`, and `deploy/frontend.Dockerfile`. GitHub Actions deployment is defined in `.github/workflows/deploy.yml`.

#### Frontend Application Shell and Access Boundary
The frontend uses page-level modules for major business areas, shared layout/navigation, and React contexts for cross-cutting state. Authentication-gated navigation is enforced by `frontend/src/components/ProtectedRoute.js`; auth state is owned by `frontend/src/contexts/AuthContext.js`; API calls are mediated through `frontend/src/utils/api.js`. The UI shell is represented by `frontend/src/components/Layout.js`, `frontend/src/components/Sidebar.js`, and `frontend/src/components/TopNav.js`.

#### Backend API and Domain Partitioning
The Python backend is organized as a route-module monolith: `backend/server.py` is the composition boundary, while modules expose domain APIs. Core business partitions include access/auth (`backend/access.py`), leads and clients (`backend/leads_v2_routes.py`, `backend/clients_routes.py`, `backend/client_master_routes.py`), and cross-domain notifications (`backend/notification_service.py`). This architecture places domain business logic and persistence-facing operations together in route files rather than a separate service layer.

#### Operations and Delivery Workflows
Operations manages clients, department projects, tasks, workflow boards, and website delivery work. Main backend boundaries are `backend/operations_routes.py`, `backend/projects_routes.py`, and `backend/website_projects_routes.py`; the user-facing operations hub is `frontend/src/pages/OperationsPage.js`. Detailed project work is surfaced through `frontend/src/pages/ProjectDetailPage.js` and board/list components such as `frontend/src/components/operations/ProjectsKanbanView.js`. Project-related Mongo collections include `db_backup/drawlead_db/department_projects.bson`, `db_backup/drawlead_db/project_tasks.bson`, and `db_backup/drawlead_db/website_projects.bson`.

#### HR, Finance, and Approval-Controlled Processes
HR covers employee profiles, attendance, leave/WFH, reviews, payroll, and organization structure through `backend/hr_routes.py`, `backend/payroll_routes.py`, and `backend/org_tree_routes.py`. Finance handles clients, banks, expenses, revenue, budgets, invoices, and payroll-linked processing via `backend/finance_routes.py`, `backend/expense_routes.py`, and `backend/banks_routes.py`; its principal frontend surface is `frontend/src/pages/FinanceModule.js`. Approval workflows form a separate control boundary in `backend/approvals_routes.py` and `frontend/src/pages/ApprovalsPage.js`. Persisted records include users, payroll settings/payslips, invoices, and expenses under `db_backup/drawlead_db/`.

#### Integrations, Automation, and External Systems
Integration-facing APIs are isolated in modules for Google Calendar/Sheets, Notion, LinkedIn, Meta reports, AI, and automation: `backend/google_calendar_routes.py`, `backend/sheets_routes.py`, `backend/notion_routes.py`, `backend/linkedin_routes.py`, `backend/meta_reports_routes.py`, `backend/ai_routes.py`, and `backend/automation_routes.py`. Corresponding frontend integration configuration is exposed through `frontend/src/components/settings/IntegrationsTab.js`. These modules are the boundary between internal records/workflows and external provider APIs.

#### Persistence and Data Flow
Requests flow from React pages/components through `frontend/src/utils/api.js` to domain API routes, which read and update MongoDB-backed entities; responses drive dashboards, boards, forms, and client-facing views. The checked-in `db_backup/drawlead_db/` BSON files indicate MongoDB as the material data store and preserve collections for identity/session, HR, finance, leads, tasks, projects, and workspaces. Database migration/restore operations are operationally separated in `deploy/migrate.sh` and `migrate_db.sh`.

Main entry points: [`backend/server.py`](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/server.py) (API composition), [`db_backup/drawlead_db/department_projects.bson`](https://github.com/drawleados-dotcom/drawleados/blob/main/db_backup/drawlead_db/department_projects.bson) (MongoDB collections), [`frontend/src/App.js`](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/App.js) (App routing and state), [`backend/operations_routes.py`](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/operations_routes.py) (Operations and projects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_browser_entry(("Browser entry<br/>React bootstrap<br/>[index.js]"))
  node_app_shell["App routing and state<br/>React application<br/>[App.js]"]
  node_access_ui["Auth and protected navigation<br/>access boundary<br/>[AuthContext.js]"]
  node_layout["Shared application shell<br/>layout components<br/>[Layout.js]"]
  node_business_ui["Business modules UI<br/>page and board views<br/>[OperationsPage.js]"]
  node_api_client["API client<br/>frontend transport<br/>[api.js]"]
end

subgraph group_backend["Python API monolith"]
  node_api_server{{"API composition<br/>Python server<br/>[server.py]"}}
  node_access_api["Access and identity<br/>route module<br/>[access.py]"]
  node_crm_api["Leads and clients<br/>route modules<br/>[leads_v2_routes.py]"]
  node_operations_api["Operations and projects<br/>route modules"]
  node_hr_api["HR and payroll<br/>route modules<br/>[hr_routes.py]"]
  node_finance_api["Finance<br/>route modules<br/>[finance_routes.py]"]
  node_approvals_api["Approval workflows<br/>route module"]
  node_integration_api["Integrations and automation<br/>provider adapters"]
  node_notifications["Notifications<br/>cross-domain service"]
end

subgraph group_data["Data and deployment"]
  node_mongodb[("MongoDB collections<br/>document database")]
  node_deployment["Container deployment<br/>Docker Compose and Nginx<br/>[docker-compose.yml]"]
  node_ci_deploy["Deployment automation<br/>GitHub Actions<br/>[deploy.yml]"]
end

subgraph group_external["External providers"]
  node_providers["Provider APIs<br/>external systems"]
end

node_browser_entry -->|"starts"| node_app_shell
node_app_shell -->|"uses"| node_access_ui
node_app_shell -->|"renders"| node_layout
node_app_shell -->|"routes to"| node_business_ui
node_business_ui -->|"requests"| node_api_client
node_access_ui -->|"auth requests"| node_api_client
node_api_client -->|"HTTP API"| node_api_server
node_api_server -->|"mounts"| node_access_api
node_api_server -->|"mounts"| node_crm_api
node_api_server -->|"mounts"| node_operations_api
node_api_server -->|"mounts"| node_hr_api
node_api_server -->|"mounts"| node_finance_api
node_api_server -->|"mounts"| node_approvals_api
node_api_server -->|"mounts"| node_integration_api
node_access_api -->|"reads and writes"| node_mongodb
node_crm_api -->|"reads and writes"| node_mongodb
node_operations_api -->|"projects and tasks"| node_mongodb
node_hr_api -->|"HR and payroll records"| node_mongodb
node_finance_api -->|"financial records"| node_mongodb
node_approvals_api -->|"approval state"| node_mongodb
node_operations_api -.->|"emits updates"| node_notifications
node_integration_api -->|"provider calls"| node_providers
node_ci_deploy -->|"deploys"| node_deployment
node_deployment -->|"runs backend"| node_api_server
node_deployment -->|"serves frontend"| node_app_shell

click node_browser_entry "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/index.js"
click node_app_shell "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/App.js"
click node_access_ui "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/contexts/AuthContext.js"
click node_layout "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/components/Layout.js"
click node_business_ui "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/pages/OperationsPage.js"
click node_api_client "https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/utils/api.js"
click node_api_server "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/server.py"
click node_access_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/access.py"
click node_crm_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/leads_v2_routes.py"
click node_operations_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/operations_routes.py"
click node_hr_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/hr_routes.py"
click node_finance_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/finance_routes.py"
click node_approvals_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/approvals_routes.py"
click node_integration_api "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/google_calendar_routes.py"
click node_notifications "https://github.com/drawleados-dotcom/drawleados/blob/main/backend/notification_service.py"
click node_mongodb "https://github.com/drawleados-dotcom/drawleados/blob/main/db_backup/drawlead_db/department_projects.bson"
click node_deployment "https://github.com/drawleados-dotcom/drawleados/blob/main/deploy/docker-compose.yml"
click node_ci_deploy "https://github.com/drawleados-dotcom/drawleados/blob/main/.github/workflows/deploy.yml"

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_browser_entry,node_app_shell,node_access_ui,node_layout,node_business_ui,node_api_client toneBlue
class node_api_server,node_access_api,node_crm_api,node_operations_api,node_hr_api,node_finance_api,node_approvals_api,node_integration_api,node_notifications toneAmber
class node_mongodb,node_deployment,node_ci_deploy toneMint
class node_providers toneRose
```

## Components

### React frontend

- [Browser entry](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/index.js): React bootstrap · `frontend/src/index.js`
- [App routing and state](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/App.js): React application · `frontend/src/App.js`
- [Auth and protected navigation](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/contexts/AuthContext.js): access boundary · Owns auth state and gates page navigation. · `frontend/src/contexts/AuthContext.js`
- [Shared application shell](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/components/Layout.js): layout components · Layout, sidebar, and top navigation. · `frontend/src/components/Layout.js`
- [Business modules UI](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/pages/OperationsPage.js): page and board views · Operations, project, finance, and approvals surfaces. · `frontend/src/pages/OperationsPage.js`
- [API client](https://github.com/drawleados-dotcom/drawleados/blob/main/frontend/src/utils/api.js): frontend transport · `frontend/src/utils/api.js`

### Python API monolith

- [API composition](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/server.py): Python server · Central process that mounts domain route modules. · `backend/server.py`
- [Access and identity](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/access.py): route module · `backend/access.py`
- [Leads and clients](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/leads_v2_routes.py): route modules · Lead, client, and client-master workflows. · `backend/leads_v2_routes.py`
- [Operations and projects](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/operations_routes.py): route modules · Department projects, tasks, and website delivery. · `backend/operations_routes.py`
- [HR and payroll](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/hr_routes.py): route modules · Employees, attendance, leave, reviews, payroll, and org structure. · `backend/hr_routes.py`
- [Finance](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/finance_routes.py): route modules · Expenses, banks, revenue, budgets, invoices, and payroll-linked processing. · `backend/finance_routes.py`
- [Approval workflows](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/approvals_routes.py): route module · `backend/approvals_routes.py`
- [Integrations and automation](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/google_calendar_routes.py): provider adapters · Calendar, Sheets, Notion, LinkedIn, Meta, AI, and automation APIs. · `backend/google_calendar_routes.py`
- [Notifications](https://github.com/drawleados-dotcom/drawleados/blob/main/backend/notification_service.py): cross-domain service · `backend/notification_service.py`

### Data and deployment

- [MongoDB collections](https://github.com/drawleados-dotcom/drawleados/blob/main/db_backup/drawlead_db/department_projects.bson): document database · Backup BSON files represent identity, HR, finance, leads, tasks, projects, and workspaces. · `db_backup/drawlead_db/department_projects.bson`
- [Container deployment](https://github.com/drawleados-dotcom/drawleados/blob/main/deploy/docker-compose.yml): Docker Compose and Nginx · Serves frontend and API in production. · `deploy/docker-compose.yml`
- [Deployment automation](https://github.com/drawleados-dotcom/drawleados/blob/main/.github/workflows/deploy.yml): GitHub Actions · `.github/workflows/deploy.yml`

### External providers

- **Provider APIs**: external systems · Google, Notion, LinkedIn, Meta, AI, and automation services.

## Connections

- Browser entry → App routing and state: starts
- App routing and state → Auth and protected navigation: uses
- App routing and state → Shared application shell: renders
- App routing and state → Business modules UI: routes to
- Business modules UI → API client: requests
- Auth and protected navigation → API client: auth requests
- API client → API composition: HTTP API
- API composition → Access and identity: mounts
- API composition → Leads and clients: mounts
- API composition → Operations and projects: mounts
- API composition → HR and payroll: mounts
- API composition → Finance: mounts
- API composition → Approval workflows: mounts
- API composition → Integrations and automation: mounts
- Access and identity → MongoDB collections: reads and writes
- Leads and clients → MongoDB collections: reads and writes
- Operations and projects → MongoDB collections: projects and tasks
- HR and payroll → MongoDB collections: HR and payroll records
- Finance → MongoDB collections: financial records
- Approval workflows → MongoDB collections: approval state
- Operations and projects → Notifications: emits updates
- Integrations and automation → Provider APIs: provider calls
- Deployment automation → Container deployment: deploys
- Container deployment → API composition: runs backend
- Container deployment → App routing and state: serves frontend