# andresilvaaaa/product_hub_crm architecture

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

- Interactive diagram: https://gitdiagram.com/andresilvaaaa/product_hub_crm
- Repository: https://github.com/andresilvaaaa/product_hub_crm

## Overview

Operations Hub is a workspace-based operations platform for software houses, with an admin dashboard and a client portal. The central business workflow moves from commercial leads and quotes through contract preparation/signing, project delivery, and invoicing; client-facing review and portal access support that workflow. The API also provides identity, platform subscriptions/usage controls, notifications, integrations, AI and agent access. Edges are limited to relationships shown in the README or source index; optional or unsampled connections are dashed and unverified.

Main entry points: [`apps/api/app/main.py`](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/main.py) (API application), [`apps/api/app/modules/contracts/service.py`](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/contracts/service.py) (Contracts and signing), [`apps/api/app/infrastructure/database.py`](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/infrastructure/database.py) (SQL database), [`apps/api/app/modules/billing/financial_fulfillment_service.py`](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/billing/financial_fulfillment_service.py) (Invoices and payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web Experience"]
  node_dashboard["Admin dashboard<br/>[page.tsx]"]
  node_portal["Client portal<br/>[page.tsx]"]
end

subgraph group_commercial["Commercial Operations"]
  node_crm["CRM and leads<br/>[service.py]"]
  node_catalog["Service catalog<br/>[service.py]"]
  node_quotes["Quotes and review<br/>[service.py]"]
  node_contracts["Contracts and signing<br/>[service.py]"]
end

subgraph group_delivery["Delivery and Billing"]
  node_projects["Project delivery<br/>[service.py]"]
  node_scope["Scope and tasks<br/>[scope_service.py]"]
  node_documents["File storage<br/>[file_storage.py]"]
  node_billing["Invoices and payments"]
end

subgraph group_platform["Platform Services"]
  node_api["API application<br/>[main.py]"]
  node_identity["Identity and access<br/>[service.py]"]
  node_database[("SQL database<br/>[database.py]")]
  node_notifications["Notifications<br/>[service.py]"]
  node_audit[("Audit and outbox<br/>[models.py]")]
  node_subscriptions["Platform billing<br/>[billing_service.py]"]
end

subgraph group_agents["AI and Integrations"]
  node_ai["AI capabilities<br/>[service.py]"]
  node_mcp["MCP agent access<br/>[server.py]"]
  node_channels["Agent channels<br/>[service.py]"]
  node_calendar["Calendar integration<br/>[google_calendar.py]"]
end

node_staff(("Workspace staff"))
node_clients(("Client users"))

node_staff -.->|"uses"| node_dashboard
node_clients -.->|"uses"| node_portal
node_dashboard -.->|"requests"| node_api
node_portal -.->|"requests"| node_api
node_api -->|"routes"| node_identity
node_api -->|"routes"| node_crm
node_api -->|"routes"| node_quotes
node_api -->|"routes"| node_contracts
node_api -->|"routes"| node_billing
node_api -->|"opens sessions"| node_database
node_crm -.->|"persists records"| node_database
node_catalog -.->|"persists catalog"| node_database
node_quotes -->|"prepares contract"| node_contracts
node_quotes -->|"records review"| node_audit
node_contracts -->|"fulfills agreement"| node_projects
node_contracts -->|"creates invoices"| node_billing
node_projects -.->|"manages scope"| node_scope
node_billing -->|"activates project"| node_projects
node_billing -->|"notifies customers"| node_notifications
node_notifications -->|"records events"| node_audit
node_subscriptions -->|"sends notices"| node_notifications
node_ai -->|"uses contract data"| node_contracts
node_ai -->|"uses project data"| node_projects
node_mcp -->|"checks agent access"| node_identity
node_mcp -->|"opens sessions"| node_database
node_channels -.->|"dispatches requests"| node_ai
node_calendar -.->|"syncs meetings"| node_api
node_documents -.->|"stores metadata"| node_database

click node_dashboard "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/web/src/app/(dashboard)/dashboard/page.tsx"
click node_portal "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/web/src/app/(portal)/portal/dashboard/page.tsx"
click node_api "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/main.py"
click node_identity "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/identity/service.py"
click node_database "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/infrastructure/database.py"
click node_crm "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/crm/service.py"
click node_catalog "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/catalog/service.py"
click node_quotes "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/commercial/service.py"
click node_contracts "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/contracts/service.py"
click node_projects "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/projects/service.py"
click node_scope "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/projects/scope_service.py"
click node_documents "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/documents/file_storage.py"
click node_billing "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/billing/financial_fulfillment_service.py"
click node_notifications "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/notifications/service.py"
click node_audit "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/audit/models.py"
click node_subscriptions "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/platform/billing_service.py"
click node_ai "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/ai/service.py"
click node_mcp "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/mcp/server.py"
click node_channels "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/channels/service.py"
click node_calendar "https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/meetings/google_calendar.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_dashboard,node_portal,node_clients toneBlue
class node_crm,node_catalog,node_quotes,node_contracts toneAmber
class node_projects,node_scope,node_documents,node_billing toneMint
class node_api,node_identity,node_database,node_notifications,node_audit,node_subscriptions toneRose
class node_ai,node_mcp,node_channels,node_calendar,node_staff toneIndigo
```

## Components

### Web Experience

- [Admin dashboard](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/web/src/app/(dashboard)/dashboard/page.tsx): `apps/web/src/app/(dashboard)/dashboard/page.tsx`
- [Client portal](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/web/src/app/(portal)/portal/dashboard/page.tsx): `apps/web/src/app/(portal)/portal/dashboard/page.tsx`

### Commercial Operations

- [CRM and leads](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/crm/service.py): `apps/api/app/modules/crm/service.py`
- [Service catalog](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/catalog/service.py): `apps/api/app/modules/catalog/service.py`
- [Quotes and review](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/commercial/service.py): `apps/api/app/modules/commercial/service.py`
- [Contracts and signing](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/contracts/service.py): `apps/api/app/modules/contracts/service.py`

### Delivery and Billing

- [Project delivery](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/projects/service.py): `apps/api/app/modules/projects/service.py`
- [Scope and tasks](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/projects/scope_service.py): `apps/api/app/modules/projects/scope_service.py`
- [File storage](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/documents/file_storage.py): `apps/api/app/modules/documents/file_storage.py`
- [Invoices and payments](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/billing/financial_fulfillment_service.py): `apps/api/app/modules/billing/financial_fulfillment_service.py`

### Platform Services

- [API application](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/main.py): `apps/api/app/main.py`
- [Identity and access](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/identity/service.py): `apps/api/app/modules/identity/service.py`
- [SQL database](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/infrastructure/database.py): `apps/api/app/infrastructure/database.py`
- [Notifications](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/notifications/service.py): `apps/api/app/modules/notifications/service.py`
- [Audit and outbox](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/audit/models.py): `apps/api/app/modules/audit/models.py`
- [Platform billing](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/platform/billing_service.py): `apps/api/app/modules/platform/billing_service.py`

### AI and Integrations

- [AI capabilities](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/ai/service.py): `apps/api/app/modules/ai/service.py`
- [MCP agent access](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/mcp/server.py): `apps/api/app/mcp/server.py`
- [Agent channels](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/channels/service.py): `apps/api/app/channels/service.py`
- [Calendar integration](https://github.com/andresilvaaaa/product_hub_crm/blob/master/apps/api/app/modules/meetings/google_calendar.py): `apps/api/app/modules/meetings/google_calendar.py`

### Other components

- **Workspace staff**
- **Client users**

## Connections

- Workspace staff → Admin dashboard: uses
- Client users → Client portal: uses
- Admin dashboard → API application: requests
- Client portal → API application: requests
- API application → Identity and access: routes (evidence: `apps/api/app/main.py`)
- API application → CRM and leads: routes (evidence: `apps/api/app/main.py`)
- API application → Quotes and review: routes (evidence: `apps/api/app/main.py`)
- API application → Contracts and signing: routes (evidence: `apps/api/app/main.py`)
- API application → Invoices and payments: routes (evidence: `apps/api/app/main.py`)
- API application → SQL database: opens sessions (evidence: `apps/api/app/infrastructure/database.py`)
- CRM and leads → SQL database: persists records
- Service catalog → SQL database: persists catalog
- Quotes and review → Contracts and signing: prepares contract (evidence: `apps/api/app/modules/contracts/service.py`)
- Quotes and review → Audit and outbox: records review
- Contracts and signing → Project delivery: fulfills agreement (evidence: `apps/api/app/modules/projects/service.py`)
- Contracts and signing → Invoices and payments: creates invoices (evidence: `apps/api/app/modules/billing/financial_fulfillment_service.py`)
- Project delivery → Scope and tasks: manages scope (evidence: `apps/api/app/modules/projects/service.py`)
- Invoices and payments → Project delivery: activates project (evidence: `apps/api/app/modules/billing/financial_fulfillment_service.py`)
- Invoices and payments → Notifications: notifies customers
- Notifications → Audit and outbox: records events (evidence: `apps/api/app/modules/notifications/service.py`)
- Platform billing → Notifications: sends notices (evidence: `apps/api/app/modules/platform/billing_service.py`)
- AI capabilities → Contracts and signing: uses contract data (evidence: `apps/api/app/modules/ai/service.py`)
- AI capabilities → Project delivery: uses project data (evidence: `apps/api/app/modules/ai/service.py`)
- MCP agent access → Identity and access: checks agent access (evidence: `apps/api/app/mcp/server.py`)
- MCP agent access → SQL database: opens sessions (evidence: `apps/api/app/mcp/server.py`)
- Agent channels → AI capabilities: dispatches requests
- Calendar integration → API application: syncs meetings
- File storage → SQL database: stores metadata
