Architecture overview

Ethos runs a field-service platform for insurance-funded building repair. Prime Ecosystem is the external job-management system of record; Ethos mirrors it into Azure SQL, layers its own booking, WIP, KPI and make-safe logic on top, and automates the work with n8n.

Edges are drawn from the repo docs (CLAUDE.md, specs) and Azure export. See the individual sections for the evidence behind each box.

Reading the layers

1. Intake: Prime Ecosystem and FreshDesk send webhooks to the Webhook receiver, which only queues them on Service Bus. Consumers and n8n pick them up.
2. Orchestration: n8n flows (scheduled, webhook, email-triggered) call stored procedures, the WebAPI and the MCP servers. Shared sub-flows handle things like fetching API tokens.
3. Services: The WebAPI is the integration hub for Prime, OptimoRoute and OpenAI. The MCP servers expose business actions to AI agents.
4. People-facing: Staff use the Admin portal; insureds, insurers and trades use the Forms portal.
5. Data: One Azure SQL database accessed only through stored procedures; BI and replica databases serve reporting and DR.
6. Browser automation: Where a partner has no API, Stagehand jobs and BrowserActions drive a remote browser (Browserbase/Playwright).

Detail: Azure · Apps · SQL · n8n