# andrewmbarros/nova architecture

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

- Interactive diagram: https://gitdiagram.com/andrewmbarros/nova
- Repository: https://github.com/andrewmbarros/nova

## Overview

NOVA is a support-inbox triage service: it fetches incoming mail, filters messages, identifies the customer or requests tax-ID clarification, then sends a reply and records a pre-ticket for ERP entry. Its README also describes escalation after failed or unanswered requests, customer/contact learning, and both IMAP/SMTP and Microsoft Graph modes. The main processor and several core modules are indexed as read, but not excerpted; their listed references and README support the broad links below, while unverified orchestration is shown dashed.

Main entry points: [`app/processor.py`](https://github.com/andrewmbarros/nova/blob/main/app/processor.py) (Triage processor), [`app/email/sender.py`](https://github.com/andrewmbarros/nova/blob/main/app/email/sender.py) (Mail gateway), [`app/database/repository.py`](https://github.com/andrewmbarros/nova/blob/main/app/database/repository.py) (Repository), [`app/worker.py`](https://github.com/andrewmbarros/nova/blob/main/app/worker.py) (Inbox worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inbox["Inbox intake"]
  node_worker["Inbox worker<br/>[worker.py]"]
  node_sources["Mail sources<br/>[sources.py]"]
  node_parser["Message parser<br/>[parser.py]"]
  node_incoming["Incoming message<br/>[models.py]"]
end

subgraph group_triage["Triage and identity"]
  node_processor["Triage processor<br/>[processor.py]"]
  node_precheck["Message filters<br/>[engine.py]"]
  node_blocklist["Blocklists<br/>[blocklist.py]"]
  node_document["Tax ID validation<br/>[validator.py]"]
  node_names["Company-name matching<br/>[names.py]"]
  node_groups["Customer group rules<br/>[groups.py]"]
end

subgraph group_records["Customer and records"]
  node_contacts["Contact resolution<br/>[contacts.py]"]
  node_customers["Customer lookup<br/>[service.py]"]
  node_repository["Repository<br/>[repository.py]"]
  node_database[("SQL database<br/>[models.py]")]
  node_states["Conversation states<br/>[states.py]"]
end

subgraph group_messaging["Replies and integrations"]
  node_templates["Reply templates<br/>[templates.py]"]
  node_sender["Mail gateway<br/>[sender.py]"]
  node_smtp{{"SMTP service"}}
  node_graph["Microsoft Graph client<br/>[graph.py]"]
  node_microsoft{{"Microsoft Graph"}}
end

subgraph group_runtime["Runtime and API"]
  node_config["Settings<br/>[config.py]"]
  node_connection["Database connection<br/>[connection.py]"]
  node_api["FastAPI routes<br/>[routes.py]"]
  node_dev["Email simulator<br/>[dev.py]"]
end

node_customer(("Email sender"))
node_team(("Support team"))
node_preticket["ERP-ready pre-ticket"]

node_customer -->|"sends email"| node_sources
node_worker -->|"fetches mail"| node_sources
node_sources -->|"parses messages"| node_parser
node_parser -->|"creates"| node_incoming
node_worker -.->|"dispatches for triage"| node_processor
node_processor -->|"filters through"| node_precheck
node_processor -->|"checks senders"| node_blocklist
node_processor -->|"checks group rules"| node_groups
node_processor -->|"resolves sender"| node_contacts
node_processor -->|"extracts and validates"| node_document
node_processor -->|"matches signature"| node_names
node_groups -->|"looks up customer"| node_customers
node_contacts -->|"reads and learns links"| node_repository
node_contacts -->|"resolves linked customer"| node_customers
node_customers -->|"normalizes tax ID"| node_document
node_processor -->|"records processing"| node_repository
node_repository -->|"reads and writes records"| node_database
node_processor -->|"applies conversation states"| node_states
node_processor -->|"builds reply text"| node_templates
node_processor -->|"sends response"| node_sender
node_sender -.->|"sends mail"| node_smtp
node_sender -->|"uses Graph gateway"| node_graph
node_sources -->|"fetches via Graph"| node_graph
node_graph -->|"calls API"| node_microsoft
node_sender -->|"escalates to team"| node_team
node_sender -->|"requests or confirms"| node_customer
node_processor -->|"builds pre-ticket"| node_preticket
node_processor -->|"hands over unresolved cases"| node_team
node_worker -->|"persists cursor and status"| node_repository
node_connection -->|"initializes schema"| node_database
node_config -->|"configures inbox"| node_worker
node_config -->|"configures gateway"| node_sender
node_api -->|"uses settings"| node_config
node_dev -->|"simulates email"| node_processor
node_dev -->|"reads recorded results"| node_repository
node_dev -->|"uses outbox"| node_sender

click node_worker "https://github.com/andrewmbarros/nova/blob/main/app/worker.py"
click node_sources "https://github.com/andrewmbarros/nova/blob/main/app/email/sources.py"
click node_parser "https://github.com/andrewmbarros/nova/blob/main/app/email/parser.py"
click node_incoming "https://github.com/andrewmbarros/nova/blob/main/app/email/models.py"
click node_processor "https://github.com/andrewmbarros/nova/blob/main/app/processor.py"
click node_precheck "https://github.com/andrewmbarros/nova/blob/main/app/rules/engine.py"
click node_blocklist "https://github.com/andrewmbarros/nova/blob/main/app/rules/blocklist.py"
click node_document "https://github.com/andrewmbarros/nova/blob/main/app/documents/validator.py"
click node_names "https://github.com/andrewmbarros/nova/blob/main/app/customers/names.py"
click node_groups "https://github.com/andrewmbarros/nova/blob/main/app/customers/groups.py"
click node_contacts "https://github.com/andrewmbarros/nova/blob/main/app/customers/contacts.py"
click node_customers "https://github.com/andrewmbarros/nova/blob/main/app/customers/service.py"
click node_repository "https://github.com/andrewmbarros/nova/blob/main/app/database/repository.py"
click node_database "https://github.com/andrewmbarros/nova/blob/main/app/database/models.py"
click node_states "https://github.com/andrewmbarros/nova/blob/main/app/rules/states.py"
click node_templates "https://github.com/andrewmbarros/nova/blob/main/app/email/templates.py"
click node_sender "https://github.com/andrewmbarros/nova/blob/main/app/email/sender.py"
click node_graph "https://github.com/andrewmbarros/nova/blob/main/app/microsoft/graph.py"
click node_config "https://github.com/andrewmbarros/nova/blob/main/app/config.py"
click node_connection "https://github.com/andrewmbarros/nova/blob/main/app/database/connection.py"
click node_api "https://github.com/andrewmbarros/nova/blob/main/app/api/routes.py"
click node_dev "https://github.com/andrewmbarros/nova/blob/main/app/api/dev.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_worker,node_sources,node_parser,node_incoming toneBlue
class node_processor,node_precheck,node_blocklist,node_document,node_names,node_groups toneAmber
class node_contacts,node_customers,node_repository,node_database,node_states toneMint
class node_templates,node_sender,node_smtp,node_graph,node_microsoft toneRose
class node_config,node_connection,node_api,node_dev,node_customer,node_team,node_preticket toneIndigo
```

## Components

### Inbox intake

- [Inbox worker](https://github.com/andrewmbarros/nova/blob/main/app/worker.py): `app/worker.py`
- [Mail sources](https://github.com/andrewmbarros/nova/blob/main/app/email/sources.py): `app/email/sources.py`
- [Message parser](https://github.com/andrewmbarros/nova/blob/main/app/email/parser.py): `app/email/parser.py`
- [Incoming message](https://github.com/andrewmbarros/nova/blob/main/app/email/models.py): `app/email/models.py`

### Triage and identity

- [Triage processor](https://github.com/andrewmbarros/nova/blob/main/app/processor.py): `app/processor.py`
- [Message filters](https://github.com/andrewmbarros/nova/blob/main/app/rules/engine.py): `app/rules/engine.py`
- [Blocklists](https://github.com/andrewmbarros/nova/blob/main/app/rules/blocklist.py): `app/rules/blocklist.py`
- [Tax ID validation](https://github.com/andrewmbarros/nova/blob/main/app/documents/validator.py): `app/documents/validator.py`
- [Company-name matching](https://github.com/andrewmbarros/nova/blob/main/app/customers/names.py): `app/customers/names.py`
- [Customer group rules](https://github.com/andrewmbarros/nova/blob/main/app/customers/groups.py): `app/customers/groups.py`

### Customer and records

- [Contact resolution](https://github.com/andrewmbarros/nova/blob/main/app/customers/contacts.py): `app/customers/contacts.py`
- [Customer lookup](https://github.com/andrewmbarros/nova/blob/main/app/customers/service.py): `app/customers/service.py`
- [Repository](https://github.com/andrewmbarros/nova/blob/main/app/database/repository.py): `app/database/repository.py`
- [SQL database](https://github.com/andrewmbarros/nova/blob/main/app/database/models.py): `app/database/models.py`
- [Conversation states](https://github.com/andrewmbarros/nova/blob/main/app/rules/states.py): `app/rules/states.py`

### Replies and integrations

- [Reply templates](https://github.com/andrewmbarros/nova/blob/main/app/email/templates.py): `app/email/templates.py`
- [Mail gateway](https://github.com/andrewmbarros/nova/blob/main/app/email/sender.py): `app/email/sender.py`
- **SMTP service**
- [Microsoft Graph client](https://github.com/andrewmbarros/nova/blob/main/app/microsoft/graph.py): `app/microsoft/graph.py`
- **Microsoft Graph**

### Runtime and API

- [Settings](https://github.com/andrewmbarros/nova/blob/main/app/config.py): `app/config.py`
- [Database connection](https://github.com/andrewmbarros/nova/blob/main/app/database/connection.py): `app/database/connection.py`
- [FastAPI routes](https://github.com/andrewmbarros/nova/blob/main/app/api/routes.py): `app/api/routes.py`
- [Email simulator](https://github.com/andrewmbarros/nova/blob/main/app/api/dev.py): `app/api/dev.py`

### Other components

- **Email sender**
- **Support team**
- **ERP-ready pre-ticket**

## Connections

- Email sender → Mail sources: sends email (evidence: `README.md`)
- Inbox worker → Mail sources: fetches mail (evidence: `app/worker.py`)
- Mail sources → Message parser: parses messages (evidence: `app/email/sources.py`)
- Message parser → Incoming message: creates (evidence: `app/email/parser.py`)
- Inbox worker → Triage processor: dispatches for triage
- Triage processor → Message filters: filters through (evidence: `app/processor.py`)
- Triage processor → Blocklists: checks senders (evidence: `app/processor.py`)
- Triage processor → Customer group rules: checks group rules (evidence: `app/processor.py`)
- Triage processor → Contact resolution: resolves sender (evidence: `app/processor.py`)
- Triage processor → Tax ID validation: extracts and validates (evidence: `app/processor.py`)
- Triage processor → Company-name matching: matches signature (evidence: `app/processor.py`)
- Customer group rules → Customer lookup: looks up customer (evidence: `app/customers/groups.py`)
- Contact resolution → Repository: reads and learns links (evidence: `app/customers/contacts.py`)
- Contact resolution → Customer lookup: resolves linked customer (evidence: `app/customers/contacts.py`)
- Customer lookup → Tax ID validation: normalizes tax ID (evidence: `app/customers/service.py`)
- Triage processor → Repository: records processing (evidence: `app/processor.py`)
- Repository → SQL database: reads and writes records (evidence: `app/database/repository.py`)
- Triage processor → Conversation states: applies conversation states (evidence: `app/processor.py`)
- Triage processor → Reply templates: builds reply text (evidence: `app/processor.py`)
- Triage processor → Mail gateway: sends response (evidence: `app/processor.py`)
- Mail gateway → SMTP service: sends mail
- Mail gateway → Microsoft Graph client: uses Graph gateway (evidence: `app/email/sender.py`)
- Mail sources → Microsoft Graph client: fetches via Graph (evidence: `app/email/sources.py`)
- Microsoft Graph client → Microsoft Graph: calls API (evidence: `app/microsoft/graph.py`)
- Mail gateway → Support team: escalates to team (evidence: `README.md`)
- Mail gateway → Email sender: requests or confirms (evidence: `README.md`)
- Triage processor → ERP-ready pre-ticket: builds pre-ticket (evidence: `README.md`)
- Triage processor → Support team: hands over unresolved cases (evidence: `README.md`)
- Inbox worker → Repository: persists cursor and status (evidence: `app/worker.py`)
- Database connection → SQL database: initializes schema (evidence: `app/database/connection.py`)
- Settings → Inbox worker: configures inbox (evidence: `app/worker.py`)
- Settings → Mail gateway: configures gateway (evidence: `app/email/sender.py`)
- FastAPI routes → Settings: uses settings (evidence: `app/api/routes.py`)
- Email simulator → Triage processor: simulates email (evidence: `app/api/dev.py`)
- Email simulator → Repository: reads recorded results (evidence: `app/api/dev.py`)
- Email simulator → Mail gateway: uses outbox (evidence: `app/api/dev.py`)
