# hugs-4-bugs/aq-os architecture

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

- Interactive diagram: https://gitdiagram.com/hugs-4-bugs/aq-os
- Repository: https://github.com/hugs-4-bugs/aq-os

## Overview

AcquisitionOS is documented as an AI market-intelligence platform for finding, qualifying, contacting, and closing business prospects. Its core workflow runs from discovery through lead scoring and audit, outreach and communication, pipeline and deal management, then proposals and revenue; analytics and real-time intelligence span those stages. The tree does not include the documented Next.js application source, so those capabilities are represented as documented subsystems rather than attributed to unsampled files. The sampled Python backend shows a separate FastAPI entry point and Celery task infrastructure; several task implementations are explicitly foundations or placeholders.

Main entry points: [`backend/app/celery_app.py`](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/celery_app.py) (Task scheduler), [`backend/app/tasks/realtime_tasks.py`](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/realtime_tasks.py) (Realtime tasks), [`backend/app/tasks/notification_tasks.py`](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/notification_tasks.py) (Notifications and reminders), [`backend/app/main.py`](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/main.py) (FastAPI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Lead acquisition"]
  node_platform["AcquisitionOS"]
  node_discovery["Business discovery"]
  node_lead[("Lead records")]
  node_qualification["Scoring and audit"]
end

subgraph group_revenue["Sales and revenue"]
  node_pipeline["Deal pipeline"]
  node_deal["Deal management"]
  node_proposal["Proposal generation"]
end

subgraph group_intelligence["Intelligence and engagement"]
  node_outreach["Outreach generation"]
  node_communication["Communication channels"]
  node_assistant["Sales assistant"]
  node_analytics["Market analytics"]
  node_notifications["Notifications and reminders"]
end

subgraph group_backend["Python backend"]
  node_api["FastAPI entry<br/>[main.py]"]
  node_database[("Async database access<br/>[database.py]")]
  node_redis[("Redis utilities<br/>[redis_client.py]")]
  node_celery["Task scheduler<br/>[celery_app.py]"]
  node_email["Email tasks<br/>[email_tasks.py]"]
  node_realtime["Realtime tasks<br/>[realtime_tasks.py]"]
  node_payment_recovery["Payment recovery"]
  node_workflows["Workflow tasks<br/>[workflow_tasks.py]"]
end

node_user(("Sales team"))

node_user -->|"uses"| node_platform
node_platform -->|"discovers businesses"| node_discovery
node_discovery -->|"creates leads"| node_lead
node_lead -->|"is scored and audited"| node_qualification
node_lead -->|"is selected for"| node_outreach
node_outreach -->|"generates messages for"| node_communication
node_communication -->|"is tracked by"| node_pipeline
node_pipeline -->|"tracks stages to"| node_deal
node_deal -->|"generates"| node_proposal
node_lead -->|"informs"| node_analytics
node_pipeline -->|"informs"| node_analytics
node_deal -->|"informs"| node_analytics
node_platform -->|"provides"| node_assistant
node_platform -->|"provides"| node_notifications
node_api -->|"checks health"| node_database
node_api -->|"checks health"| node_redis
node_celery -->|"routes tasks"| node_email
node_celery -->|"routes tasks"| node_notifications
node_celery -->|"routes and schedules"| node_realtime
node_celery -->|"routes tasks"| node_payment_recovery
node_celery -->|"routes and schedules"| node_workflows
node_realtime -->|"delegates email"| node_email
node_realtime -->|"delegates push"| node_notifications

click node_notifications "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/notification_tasks.py"
click node_api "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/main.py"
click node_database "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/database.py"
click node_redis "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/redis_client.py"
click node_celery "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/celery_app.py"
click node_email "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/email_tasks.py"
click node_realtime "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/realtime_tasks.py"
click node_payment_recovery "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/payment_recovery_tasks.py"
click node_workflows "https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/workflow_tasks.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_platform,node_discovery,node_lead,node_qualification toneBlue
class node_pipeline,node_deal,node_proposal toneAmber
class node_outreach,node_communication,node_assistant,node_analytics,node_notifications toneMint
class node_api,node_database,node_redis,node_celery,node_email,node_realtime,node_payment_recovery,node_workflows toneRose
class node_user toneIndigo
```

## Components

### Lead acquisition

- **AcquisitionOS**
- **Business discovery**
- **Lead records**
- **Scoring and audit**

### Sales and revenue

- **Deal pipeline**
- **Deal management**
- **Proposal generation**

### Intelligence and engagement

- **Outreach generation**
- **Communication channels**
- **Sales assistant**
- **Market analytics**
- [Notifications and reminders](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/notification_tasks.py): `backend/app/tasks/notification_tasks.py`

### Python backend

- [FastAPI entry](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/main.py): `backend/app/main.py`
- [Async database access](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/database.py): `backend/app/database.py`
- [Redis utilities](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/redis_client.py): `backend/app/redis_client.py`
- [Task scheduler](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/celery_app.py): `backend/app/celery_app.py`
- [Email tasks](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/email_tasks.py): `backend/app/tasks/email_tasks.py`
- [Realtime tasks](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/realtime_tasks.py): `backend/app/tasks/realtime_tasks.py`
- [Payment recovery](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/payment_recovery_tasks.py): `backend/app/tasks/payment_recovery_tasks.py`
- [Workflow tasks](https://github.com/hugs-4-bugs/aq-os/blob/main/backend/app/tasks/workflow_tasks.py): `backend/app/tasks/workflow_tasks.py`

### Other components

- **Sales team**

## Connections

- Sales team → AcquisitionOS: uses
- AcquisitionOS → Business discovery: discovers businesses
- Business discovery → Lead records: creates leads
- Lead records → Scoring and audit: is scored and audited
- Lead records → Outreach generation: is selected for
- Outreach generation → Communication channels: generates messages for
- Communication channels → Deal pipeline: is tracked by
- Deal pipeline → Deal management: tracks stages to
- Deal management → Proposal generation: generates
- Lead records → Market analytics: informs
- Deal pipeline → Market analytics: informs
- Deal management → Market analytics: informs
- AcquisitionOS → Sales assistant: provides
- AcquisitionOS → Notifications and reminders: provides
- FastAPI entry → Async database access: checks health (evidence: `backend/app/main.py`)
- FastAPI entry → Redis utilities: checks health (evidence: `backend/app/main.py`)
- Task scheduler → Email tasks: routes tasks (evidence: `backend/app/celery_app.py`)
- Task scheduler → Notifications and reminders: routes tasks (evidence: `backend/app/celery_app.py`)
- Task scheduler → Realtime tasks: routes and schedules (evidence: `backend/app/celery_app.py`)
- Task scheduler → Payment recovery: routes tasks (evidence: `backend/app/celery_app.py`)
- Task scheduler → Workflow tasks: routes and schedules (evidence: `backend/app/celery_app.py`)
- Realtime tasks → Email tasks: delegates email (evidence: `backend/app/tasks/realtime_tasks.py`)
- Realtime tasks → Notifications and reminders: delegates push (evidence: `backend/app/tasks/realtime_tasks.py`)
