API Diagrams¶

Executive Summary¶

API Diagrams provides Mermaid diagrams for the Algosure API architecture. The diagrams describe logical API boundaries, security flow, command/query responsibility separation, AIOS tool calls, integration separation, and future documentation flow.

Why This Exists¶

The API architecture crosses mobile, web, AIOS, integrations, security, Domains, events, and future OpenAPI contracts. Diagrams make those boundaries easier to review without creating endpoint specs.

Owner¶

The owner is the Chief Product Officer and Enterprise Architect.

Business Value¶

The diagrams give product, architecture, engineering, security, AI, and integration teams a shared visual API baseline.

API Boundary Diagram¶

flowchart TB
    Mobile[Mobile App]
    Web[Web App]
    AIOS[AIOS Tool Calls]
    External[External Systems]

    Public[Public Application APIs]
    Internal[Governed Internal APIs]
    Integration[Integration APIs]

    Backend[Spring Boot Modulith Backend]
    Domains[Domain-Owned API Boundaries]

    Mobile --> Public
    Web --> Public
    AIOS --> Internal
    External --> Integration
    Public --> Backend
    Internal --> Backend
    Integration --> Backend
    Backend --> Domains

Security Diagram¶

flowchart LR
    Request[API Request]
    Authn[Authentication]
    Tenant[Tenant Context]
    Org[Organization Context]
    Authz[Authorization]
    Role[Role and Permission Checks]
    Entitlement[Entitlement Checks]
    Domain[Domain API]
    Audit[Audit Trail]

    Request --> Authn
    Authn --> Tenant
    Tenant --> Org
    Org --> Authz
    Authz --> Role
    Role --> Entitlement
    Entitlement --> Domain
    Domain --> Audit

Command and Query Diagram¶

flowchart TB
    API[Domain-Owned API Resource]
    Command[Command Responsibility]
    Query[Query Responsibility]
    App[Application Service]
    Domain[Domain Model]
    Projection[Read Model or Projection]
    Event[Domain Event]

    API --> Command
    API --> Query
    Command --> App
    Query --> App
    App --> Domain
    App --> Projection
    Domain --> Event

AIOS Tool Call Diagram¶

sequenceDiagram
    participant AIOS as AIOS
    participant Internal as Governed Internal API
    participant Security as Security Checks
    participant Domain as Owning Domain
    participant Audit as Audit Trail

    AIOS->>Internal: Request scoped tool action
    Internal->>Security: Validate tenant, organization, permission, entitlement
    Security->>Domain: Execute through application service
    Domain-->>Internal: Return governed result
    Internal->>Audit: Record tool call and result
    Internal-->>AIOS: Return scoped response

Integration Separation Diagram¶

flowchart LR
    External[External Partner or System]
    IntegrationAPI[Integration API Boundary]
    IntegrationGateway[Integration Gateway]
    Domain[Owning Domain API]
    Event[Integration or Domain Event]

    External --> IntegrationAPI
    IntegrationAPI --> IntegrationGateway
    IntegrationGateway --> Domain
    Domain --> Event

Future Documentation Diagram¶

flowchart LR
    Architecture[API Architecture]
    DomainDesign[Domain API Design]
    OpenAPI[Future OpenAPI Contract]
    Review[Security and Architecture Review]
    Consumers[Mobile, Web, AIOS, Integrations]

    Architecture --> DomainDesign
    DomainDesign --> OpenAPI
    OpenAPI --> Review
    Review --> Consumers

Diagram Notes¶

APIs are REST-first.
API boundaries are domain-owned.
Mobile and web use public application APIs.
AIOS tool calls use governed internal APIs.
Integration APIs are separated from internal APIs.
Security, tenant context, organization context, authorization, permissions, entitlements, idempotency, and audit apply at API boundaries.
OpenAPI is a future contract source, not created in this architecture task.