# naghi20/aqari-ai architecture

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

- Interactive diagram: https://gitdiagram.com/naghi20/aqari-ai
- Repository: https://github.com/naghi20/aqari-ai

## Overview

AQARI AI is a serverless real-estate listing assistant. In the implemented baseline, an agent’s property payload is validated, converted into a privacy-filtered AI context, and stored as a draft in DynamoDB; a separate Lambda handler reports health. The README describes a broader MVP and roadmap: private photo storage, Bedrock-generated listing and social content, human approval, and manual Joomla export. Those future capabilities are shown as planned, not as implemented flows. Arrows for the current create path are supported by excerpts; planned integrations are dashed because their runtime wiring is not present in the sampled source.

Main entry points: [`backend/src/aqari_ai/handlers/create_property.py`](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/handlers/create_property.py) (Create draft), [`backend/src/aqari_ai/services/validation_service.py`](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/validation_service.py) (Verified context), [`backend/src/aqari_ai`](https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai) (Draft content package), [`backend/src/aqari_ai/services/dynamodb_service.py`](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/dynamodb_service.py) (Draft persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request handlers"]
  node_api{{"API Gateway"}}
  node_create["Create draft<br/>[create_property.py]"]
  node_health["Health check<br/>[health.py]"]
end

subgraph group_domain["Property domain"]
  node_model["Property draft model<br/>[property.py]"]
  node_context["Verified context"]
end

subgraph group_storage["Draft storage"]
  node_draftstore["Draft persistence"]
  node_dynamodb[("DynamoDB")]
end

subgraph group_planned["Planned listing workflow"]
  node_photos["Private photos"]
  node_s3[("Amazon S3")]
  node_generation["Listing generation"]
  node_bedrock{{"Amazon Bedrock"}}
  node_content["Draft content package"]
  node_review(("Human review"))
  node_export["Joomla export"]
  node_social["Social drafts"]
end

node_agent(("Authorized agent"))

node_agent -.->|"submits facts"| node_api
node_api -.->|"routes request"| node_create
node_create -->|"validates payload"| node_model
node_create -->|"builds context"| node_context
node_context -->|"reads fields"| node_model
node_create -->|"writes draft"| node_draftstore
node_draftstore -->|"stores item"| node_dynamodb
node_agent -.->|"checks service"| node_health
node_photos -.->|"stores originals"| node_s3
node_context -.->|"supplies verified facts"| node_generation
node_generation -.->|"generates text"| node_bedrock
node_bedrock -.->|"returns drafts"| node_content
node_content -.->|"requires approval"| node_review
node_review -.->|"approves export"| node_export
node_content -.->|"produces drafts"| node_social

click node_create "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/handlers/create_property.py"
click node_health "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/handlers/health.py"
click node_model "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/models/property.py"
click node_context "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/validation_service.py"
click node_draftstore "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/dynamodb_service.py"
click node_photos "https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai"
click node_generation "https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/prompts/listing_generation_v1.txt"
click node_content "https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai"
click node_export "https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai"
click node_social "https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai"

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_api,node_create,node_health toneBlue
class node_model,node_context toneAmber
class node_draftstore,node_dynamodb toneMint
class node_photos,node_s3,node_generation,node_bedrock,node_content,node_review,node_export,node_social toneRose
class node_agent toneIndigo
```

## Components

### Request handlers

- **API Gateway**
- [Create draft](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/handlers/create_property.py): `backend/src/aqari_ai/handlers/create_property.py`
- [Health check](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/handlers/health.py): `backend/src/aqari_ai/handlers/health.py`

### Property domain

- [Property draft model](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/models/property.py): `backend/src/aqari_ai/models/property.py`
- [Verified context](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/validation_service.py): `backend/src/aqari_ai/services/validation_service.py`

### Draft storage

- [Draft persistence](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/services/dynamodb_service.py): `backend/src/aqari_ai/services/dynamodb_service.py`
- **DynamoDB**

### Planned listing workflow

- [Private photos](https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai): `backend/src/aqari_ai`
- **Amazon S3**
- [Listing generation](https://github.com/naghi20/aqari-ai/blob/main/backend/src/aqari_ai/prompts/listing_generation_v1.txt): `backend/src/aqari_ai/prompts/listing_generation_v1.txt`
- **Amazon Bedrock**
- [Draft content package](https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai): `backend/src/aqari_ai`
- **Human review**
- [Joomla export](https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai): `backend/src/aqari_ai`
- [Social drafts](https://github.com/naghi20/aqari-ai/tree/main/backend/src/aqari_ai): `backend/src/aqari_ai`

### Other components

- **Authorized agent**

## Connections

- Authorized agent → API Gateway: submits facts (evidence: `README.md`)
- API Gateway → Create draft: routes request (evidence: `README.md`)
- Create draft → Property draft model: validates payload (evidence: `backend/src/aqari_ai/handlers/create_property.py`)
- Create draft → Verified context: builds context (evidence: `backend/src/aqari_ai/handlers/create_property.py`)
- Verified context → Property draft model: reads fields (evidence: `backend/src/aqari_ai/services/validation_service.py`)
- Create draft → Draft persistence: writes draft (evidence: `backend/src/aqari_ai/handlers/create_property.py`)
- Draft persistence → DynamoDB: stores item (evidence: `backend/src/aqari_ai/services/dynamodb_service.py`)
- Authorized agent → Health check: checks service (evidence: `README.md`)
- Private photos → Amazon S3: stores originals (evidence: `README.md`)
- Verified context → Listing generation: supplies verified facts (evidence: `README.md`)
- Listing generation → Amazon Bedrock: generates text (evidence: `README.md`)
- Amazon Bedrock → Draft content package: returns drafts (evidence: `README.md`)
- Draft content package → Human review: requires approval (evidence: `README.md`)
- Human review → Joomla export: approves export (evidence: `README.md`)
- Draft content package → Social drafts: produces drafts (evidence: `README.md`)
