TorbatYar/docs/crm-phase-6-0.md

# Phase 6.0 — CRM Service Foundation

| Field | Value |
| --- | --- |
| Status | Complete |
| Module | crm |
| Version | 0.6.0.0 |
| Database | `crm_db` |
| API Port | 8003 |
| ADR | ADR-001, ADR-003, ADR-006 |

## Goal

Establish the Sales CRM service foundation and architectural boundaries only.
No Customer360, Automation, Marketing, Communication, Helpdesk, Analytics, or AI platforms.

## CRM Responsibilities

CRM owns **Sales CRM** domain only:

- Lead
- Contact
- Organization (business account)
- Opportunity
- Pipeline / PipelineStage
- SalesActivity (meeting / call / task / note)
- Quote (sales quote only)
- CRM timeline event **source** contracts (publish)

## Service Boundaries

| CRM owns | CRM does not own |
| --- | --- |
| Sales aggregates above | Workflow / Automation |
| CRM HTTP APIs under `/api/v1/*` | Customer360 |
| `crm.*` permissions | Marketing |
| Publish-only CRM events | Notification / Messaging / Communication |
| Platform provider **interfaces** | Helpdesk / Analytics / AI |
| | Identity / Accounting / Inventory |
| | Restaurant / Marketplace / Files / Search |

Communication with platform services is **API + Events only**. No cross-DB access.

## Owned Modules (aggregates)

Independent aggregates in `backend/services/crm/app/models/foundation.py`:

1. `Lead`
2. `Contact`
3. `Organization`
4. `Opportunity`
5. `Pipeline`
6. `PipelineStage`
7. `SalesActivity`
8. `Quote`

Cross-aggregate links use UUID references inside `crm_db` only (no SQLAlchemy relationship graphs).

## External Platform Dependencies (contracts only)

Defined in `app/providers/contracts.py` — **no implementations**:

- `AutomationProvider`
- `Customer360Provider`
- `NotificationProvider`
- `AnalyticsProvider`
- `AIProvider`
- `CommunicationProvider`
- `HelpdeskProvider`

## Published Events

| Event | Aggregate |
| --- | --- |
| `crm.lead.created` | lead |
| `crm.lead.updated` | lead |
| `crm.contact.created` | contact |
| `crm.opportunity.created` | opportunity |
| `crm.opportunity.won` | opportunity |
| `crm.activity.completed` | sales_activity |
| `crm.quote.created` | quote |

Phase 6.0 does **not** consume future platform events.

## API Contracts

| Method | Path |
| --- | --- |
| CRUD | `/api/v1/leads` |
| CRUD | `/api/v1/contacts` |
| CRUD | `/api/v1/organizations` |
| CRUD + stages | `/api/v1/pipelines` |
| CRUD + win | `/api/v1/opportunities` |
| CRUD + complete | `/api/v1/activities` |
| CRUD | `/api/v1/quotes` |
| Health | `/health` |

No Automation / Customer360 / Notification APIs are exposed.

## Permissions

- `crm.*`
- `crm.leads.*`
- `crm.contacts.*`
- `crm.organizations.*`
- `crm.opportunities.*`
- `crm.activities.*`
- `crm.quotes.*`

## Architecture Decisions

1. Database-per-service (`crm_db`) — ADR-001
2. Row-level `tenant_id` from request tenant context — ADR-003
3. Event publish contracts via `EventEnvelope` — ADR-006
4. Layering: API → Services → Repositories → Models
5. Platform capabilities stay behind provider protocols; CRM never implements them

## Folder Structure

```
backend/services/crm/
  app/
    api/v1/
    core/
    middlewares/
    models/
    repositories/
    services/
    validators/
    schemas/
    events/
    permissions/
    providers/
    tests/
  alembic/versions/0001_initial.py
  scripts/ensure_db.py
  README.md
```

## Future Roadmap (beyond foundation)

- Provider adapters when sibling platforms exist
- Frontend CRM module UI
- Outbox worker wiring to real message bus

Phases 6.1–6.3 completed — see [crm-phase-6-3.md](crm-phase-6-3.md).
## Completion Checklist

- [x] Code completed
- [x] Architecture / dependency / repository / migration / API / permission / tenant / docs tests
- [x] Documentation updated
- [x] Module registry updated
- [x] No forbidden platform ownership
- [x] No TODO placeholders in foundation

## Related Documents

- [Progress](progress.md)
- [Next Steps](next-steps.md)
- [Module Registry — crm](module-registry.md#crm)
- [CRM Phase Area](phases/CRM/README.md)
- [Service README](../backend/services/crm/README.md)