WhatsApp-first quoting assistant for Brazilian construction material stores. Automates quote generation, pricing, and approval workflows via WhatsApp Cloud API.
- WhatsApp Integration: Receive quote requests and send formatted quotes via WhatsApp Cloud API
- Automated Quoting: Deterministic pricing engine with volume discounts, freight calculation, and payment method discounts
- Multi-Tenant SaaS: Host-based routing with strict tenant isolation
- Approval Workflow: Human-in-the-loop approval for edge cases (unknown SKUs, low margins, high values)
- Admin Panel: HTMX-based server-rendered dashboard for quote approvals and configuration
┌─────────────────────────────────────────────────────────┐
│ WhatsApp Cloud API │
└────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ FastAPI Application (Uvicorn) │
│ ├── Webhook endpoints │
│ ├── Admin panel (HTMX) │
│ └── API endpoints │
└────────────────────┬────────────────────────────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Redis │
│ (Database) │ │ (Queue/Cache)│
└──────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ RQ Workers │
│ (Background) │
└──────────────┘
Components:
- API: FastAPI application handling webhooks, admin panel, and API endpoints
- Worker: RQ workers processing background jobs (message processing, quote generation)
- Database: PostgreSQL for persistent data
- Queue: Redis for job queue and session storage
Multi-Tenancy:
- Host-based routing:
{slug}.orcazap.comfor tenant dashboards api.orcazap.comfor API endpoints and webhooksorcazap.comfor public pages- All queries filtered by
tenant_idfor isolation
- Python 3.12+
- PostgreSQL 15+
- Redis 7+
- Poetry (recommended) or pip
- Clone and install dependencies:
git clone <repo-url>
cd orcazap
poetry install # or: pip install -r requirements.txt- Set up environment:
cp env.example .env
# Edit .env with your configuration- Set up database:
createdb orcazap
alembic upgrade head- Start services:
# Terminal 1: Start API
uvicorn app.main:app --reload
# Terminal 2: Start worker
rq worker --url redis://localhost:6379/0 default- Run tests:
pytest- Webhook receives message: WhatsApp Cloud API sends webhook → FastAPI stores message → enqueues job
- Worker processes: RQ worker picks up job → creates/updates contact & conversation → state machine transition
- Data capture: Customer provides CEP, payment method, delivery day, items → worker parses message
- Quote generation: Pricing engine calculates quote → checks approval rules → auto-approve or require human approval
- Approval (if needed): Admin reviews in HTMX dashboard → approves/rejects → quote sent via WhatsApp
- Quote sent: Formatted quote message sent → conversation state updated → customer can accept/decline
See docs/flows.md for detailed flow diagrams.
- Documentation Index - Complete documentation navigation
- Architecture - System design and boundaries
- Flows - End-to-end application flows
- Security - Security model and tenant isolation
- Deployment - Production deployment guide
- Backend: Python 3.12+, FastAPI, SQLAlchemy 2.0, Alembic
- Queue: Redis, RQ (Redis Queue)
- Frontend: HTMX, Jinja2 templates
- Database: PostgreSQL 15+
- Testing: pytest
- Code Quality: ruff, mypy
# Format code
ruff format .
# Lint code
ruff check .
# Type check
mypy app
# Run tests
pytest
# Run with coverage
pytest --cov=app --cov-report=htmlNo sensitive production data in public documentation:
- No real IP addresses or domains
- No tokens, keys, or passwords
- All secrets documented as required environment variables with placeholders
- Private infrastructure details kept in private runbooks
If you find sensitive information in public docs, please report it.
[To be determined]