Opensure

Theme

Opensure v2 Platform – Architecture Overview ​

Opensure is a developer friendly, full-stack, multi-tenant insurance operations platform that aims to be the HTTP of insurance operations. It is built on a production-grade and extensible framework.

Django 4.2 LTS backend on Python 3.12 + PostgreSQL exposes a REST API and MCP-ready endpoints, a React 18 + TypeScript + Vite dashboard provides the primary user experience, and surrounding modules—including a Rule Studio automation engine, connectors framework (email, Stripe, database), an MCP server package, and a MarketFinder Chrome extension, that let teams model, automate, and operate insurance workflows safely at scale.

1. High-Level Goals ​

Opensure v2 is a multi-tenant insurance operations platform with three primary goals:

  • Multi-tenant core – shared infrastructure with strict tenant isolation.
  • Extensibility – rule engine + connectors (email, payments, databases) as first-class modules.
  • MCP-first design – Model Context Protocol (MCP) tools that let AI agents operate safely on tenant data.

2. Frontend Architecture (React + Vite) ​

3.1 Project Layout ​

  • dashboard/ – frontend root:
    • src/ – main application code.
    • opensure-docs/ – embedded documentation project (source for docs.opensure.dev; see Section 6).
    • public/ – static assets (including docs mirror in public/docs).
    • vite.config.ts – Vite configuration.
    • tailwind.config.js – TailwindCSS configuration.

3.2 Application Shell ​

  • dashboard/src/main.tsx
    • Initializes Sentry (if DSN is configured).
    • Renders <App /> into the root element.
  • dashboard/src/App.tsx
    • Sets up routing with react-router-dom.
    • Wraps the app in:
      • AuthProvider – authentication context.
      • ToastProvider – notifications.
      • DashboardLayout – shared layout for logged-in views.
    • Uses ProtectedRoute to enforce authentication on most routes.
    • Uses React.lazy + Suspense to code-split feature pages.

3.3 Route Map ​

Public Routes

  • /login – login page.
  • /signup – signup/registration.
  • /register – redirect to /signup.
  • /verify-email – email verification step.
  • /accept-invite – accept team invitations.

Protected Core Routes

  • / → redirects to /dashboard.
  • /dashboard – primary overview/dashboard experience.
  • /profile – user profile.
  • /account – account settings.
  • /getting-started – onboarding checklist.

Rule Studio & Connectors

  • /rule-studio – visual rule builder (Rule Studio).
  • /connectors – connectors management UI.
  • /api-keys – API key management.
  • /llm-adapter – LLM integration configuration.
  • /extensions – extensions and integrations overview.

Market Finder

  • /customers, /quotes, /policies, /claims, /reports – Market Finder pages, often gated behind a marketFinderInstalled prop on the layout.

Documentation & Community

  • /docs – entrypoint into documentation.
  • /docs/getting-started and nested routes – in-app documentation browser.
  • /docs/:section and /docs/:section/:page – dynamic documentation routes.
  • /discord – community/Discord integration.

3.4 Integration with Backend ​

  • Configuration uses environment variables (for example, API base URL, Sentry DSN) via Vite’s import.meta.env.
  • The dashboard communicates with the Django backend (typically at http://localhost:3001 in development) for:
    • Auth and team endpoints.
    • Rule Studio APIs.
    • Connectors (email/Stripe) and Market Finder data.
    • Settings and MCP-related features (API keys, databases).

3. MCP Server Architecture (mcp-server/) ​

The MCP server is a separate TypeScript package that allows MCP clients (for example, Claude Desktop) to safely use Opensure as a control plane over a tenant’s own database.

4.1 Responsibilities ​

  • Implements an MCP server over stdio (JSON-RPC 2.0).
  • Authenticates with the Opensure backend using an API key.
  • Obtains the tenant’s identity from the backend and enforces:
    • tenant_id scoping on all queries.
    • Per-tenant isolation for read/write operations.
  • Exposes a set of tools for managing insurance clients and policies:
    • client.create, client.get, client.list, client.update
    • policy.create, policy.get, policy.list, policy.update

4.2 Data Flow ​

  1. MCP client (e.g., Claude Desktop) calls an MCP tool such as client.create.
  2. The MCP server:
    • Validates the Opensure API key against the backend.
    • Determines the tenant id associated with that key.
  3. The MCP server connects to the tenant’s database (for example, a Postgres instance provisioned by the tenant).
  4. Every query is executed with tenant_id filters applied by design.

The end result: AI tooling can help manage insurance data, but actual customer and policy data lives in the tenant’s database, not Opensure’s servers.

4. MarketFinder Chrome Extension ​

The MarketFinder Chrome extension (extensions/market-finder-chrome/) provides a lightweight way for insurance agents to onboard and interact with Market Finder directly from the browser.

5.1 Goals ​

  • Zero-friction onboarding:
    • Auto-provision a tenant account on first install.
    • Provide the agent with an API key linked to that tenant.
  • Browser-native assistance:
    • (Planned) Analyze websites visited by the agent to infer industry and coverage needs.
    • Surface relevant Market Finder information and carrier matches.

5.2 Architecture ​

  • Stack:
    • React 18 + TypeScript + Vite.
    • Manifest V3 Chrome extension.
  • Key components:
    • popup/ – main popup UI entrypoint.
    • components/Onboarding.tsx – onboarding flow for new agents.
    • lib/api.ts – HTTP client for talking to the Opensure backend.
    • lib/storage.ts – chrome.storage utilities for secure local storage.
    • background/ – service worker for background tasks.
    • Content scripts for page analysis (in future tasks).

5.3 Backend Integration ​

  • Onboarding flow:
    • Calls a tenant provisioning endpoint on the Opensure backend.
    • Receives a tenant id and API key.
    • Stores the key and tenant id securely in Chrome’s local storage.
  • Subsequent calls use:
    • Bearer token authentication.
    • Tenant-aware headers (for example, an X-Tenant-Id style pattern).
  • This extension is conceptually aligned with:
    • The Market Finder Django app (apps/market_finder).
    • The dashboard’s Market Finder pages and settings.

5. Documentation Architecture (docs.opensure.dev) ​

Opensure v2 includes a documentation pipeline that publishes content from this repo to https://docs.opensure.dev.

6.1 Authoring Locations ​

  • Primary documentation sources:
    • dashboard/opensure-docs/docs/** – structured docs for:
      • Getting started.
      • Developer guides.
      • MCP tools.
      • Database schemas.
      • Concepts and reference material.
    • docs/** – additional reference and operational docs (schema files, setup guides, deployment runbooks, etc.).

6.2 Sync Pipeline ​

  1. Content is authored/updated in dashboard/opensure-docs/docs and docs.
  2. A sync step mirrors content into dashboard/public/docs/ (the staging area).
  3. From there, Opensure-Docs (a separate repository) is updated via:
    • A scheduled GitHub Action (.github/workflows/sync-docs.yml) and/or
    • A local script such as ./scripts/sync-docs.sh.
  4. That sync step:
    • Copies the staged docs into the Opensure-Docs working tree.
    • Updates timestamps/index files.
    • Commits and pushes to the Opensure-Docs GitHub repository.

6.3 Deployment to docs.opensure.dev ​

  • Vercel project: opensure-docs.
  • Connected repository: Opensure-Docs.
  • Behavior:
    • Every push to main triggers a deploy.
    • Custom domain docs.opensure.dev serves the resulting static site.
  • Important URLs:
    • https://docs.opensure.dev/
    • https://docs.opensure.dev/mcp/quickstart.md
    • https://docs.opensure.dev/schema/opensure_schema_v2.2.0.md

6.4 Dashboard Integration ​

  • The dashboard’s Documentation pages (dashboard/src/pages/DocumentationPage.tsx and related components) link directly to https://docs.opensure.dev and its sections.
  • The dashboard acts as a launcher and in-context navigator, while the docs site is the authoritative source of truth.

6. Cross-Cutting Concerns ​

7.1 Multi-Tenancy ​

  • Tenant isolation is enforced across:
    • Django apps and ORM queries.
    • Connectors and external databases.
    • MCP server tooling.
    • Chrome extension flows.
  • Typical pattern:
    • A validated API key is associated with a tenant.
    • That tenant id scopes all reads and writes.

7.2 Safety & Quality Gates ​

  • tools/ contains custom linters and guards:
    • Naming lint for schemas and models.
    • Migration guards to avoid unsafe migrations.
    • Template and DDL linters.
  • .claude/ and specs/ store:
    • Governance, protocols, and patterns.
    • Security audits and incident retrospectives.
    • Product and platform PRDs.
  • CI and pre-commit:
    • Enforce style, correctness, and safety checks before changes are accepted.

7. How to Extend the Platform Safely ​

When adding new features or integrations:

  1. Consult the specs and protocols
    • Read the relevant documents under specs/ and .claude/critical / .claude/protocols for the area you’re changing.
  2. Respect multi-tenancy
    • Ensure new models and queries are tenant-aware.
    • Avoid any cross-tenant data access patterns.
  3. Reuse existing patterns
    • For new connectors, follow patterns in apps/connectors.
    • For new rule types, follow patterns in apps/rules.
    • For docs, follow the dashboard/opensure-docs/docs structure so they flow to docs.opensure.dev.
  4. Validate with tooling
    • Use make check and make test before merging changes.
    • Run schema and migration linters when touching database models or DDL.

This approach keeps Opensure v2 coherent, secure, and aligned with its long-term architecture and product vision.

Built with VitePress

Copyright © 2025 Opensure