API Architecture¶

Executive Summary¶

API Architecture defines the logical API architecture for Algosure. APIs are REST-first, domain-owned, secure-by-design, multi-tenant by design, and aligned to the Spring Boot Modulith backend.

Why This Exists¶

Algosure exposes capabilities to the mobile app, web app, AIOS tool calls, and external integrations. API architecture must preserve Domain ownership, tenant isolation, authorization, entitlement governance, command/query responsibility separation, and future contract documentation.

Owner¶

The owner is the Chief Product Officer and Enterprise Architect.

Business Value¶

A governed API architecture reduces coupling, improves client consistency, protects source-domain ownership, and creates a path toward formal OpenAPI contracts without creating endpoint specifications prematurely.

API Architecture View¶

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

    PublicAPI[External / Public API Boundary]
    InternalAPI[Internal API Boundary]
    IntegrationAPI[Integration API Boundary]

    Auth[Authentication, Authorization, Entitlements]
    Backend[Spring Boot Modulith Backend]
    Domains[Domain-Owned API Boundaries]

    Mobile --> PublicAPI
    Web --> PublicAPI
    AIOS --> InternalAPI
    External --> IntegrationAPI
    PublicAPI --> Auth
    InternalAPI --> Auth
    IntegrationAPI --> Auth
    Auth --> Backend
    Backend --> Domains

API Categories¶

API Category	Purpose
Public application APIs	Support mobile and web app experiences through governed, tenant-aware, domain-owned contracts.
Internal APIs	Support backend-to-backend, AIOS tool calls, internal workflows, and module coordination where events are not the right mechanism.
Integration APIs	Support external system and partner interactions through separated integration boundaries.
Future OpenAPI contracts	Formal API contract source for documentation, review, testing, and client generation when endpoint design is approved.
Future GraphQL	May be considered only when justified by client composition complexity, read aggregation needs, and security review.

Domain-Owned API Boundaries¶

Domain	API Boundary Ownership
Identity	Authentication interpretation, memberships, roles, permissions, sessions, API keys, MFA, authorization policy facts.
Organization	Tenant root, organization profile, organization context, customer operating context.
Compliance	Compliance readiness, evidence, verification, expiry, and risk.
Opportunity	Tender discovery, matching, saved opportunities, deadlines, and recommendations.
Bid	Bid workspaces, tasks, documents, approvals, and submission readiness.
Contract	Awarded contracts, delivery, milestones, invoices, payments, performance, and closeout.
Supplier	Supplier profiles, relationships, quotes, trust state, and performance.
Marketplace	Listings, supplier discovery, quote requests, matching, and marketplace workflows.
Funding	Funding needs, readiness, applications, offers, and repayment context.
Learning	Courses, lessons, progress, certificates, learning paths, and maturity learning.
Intelligence	AIOS work, reasoning, explanations, memory workflows, and AI task outcomes.
Notification	Preferences, notification intent, delivery history, reminders, and escalations.
Analytics	Dashboards, KPIs, reports, metric snapshots, and executive insights.
Billing	Plans, subscriptions, invoices, payments, entitlements, limits, and renewals.
Administration	Configuration, feature flags, support actions, audit review, policies, and governance.

Core Rules¶

Rule	Requirement
REST-first	REST is the default API style for Algosure application and integration APIs.
Domain-owned	APIs belong to the Domain that owns the business capability and source facts.
Command/query responsibility separation	API responsibilities must distinguish state-changing commands from read-oriented queries.
Multi-tenant by design	Tenant and organization context must be explicit, validated, and auditable.
Secure by design	Authentication, authorization, role and permission checks, entitlement checks, and audit apply at API boundaries.
Idempotency for unsafe commands	State-changing APIs that may be retried must support idempotency keys.
Integration separation	Integration APIs are separate from internal APIs and public application APIs.
No endpoint specs yet	This layer defines architecture standards, not final routes or request schemas.

Non-Implementation Boundary¶

This document does not define final endpoint paths, request payloads, response payloads, controller classes, OpenAPI files, framework annotations, or gateway configuration.