API Resource Model

Executive Summary

API Resource Model defines how REST resources should be shaped logically for Algosure. Resources reflect domain-owned business concepts and must separate command and query responsibilities at the API responsibility level.

Why This Exists

Resource design is where APIs often drift toward screens, tables, or technical shortcuts. Algosure APIs must remain aligned to Domains, tenant context, organization context, application services, and source ownership.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

A consistent resource model gives mobile, web, AIOS, and integration consumers predictable contracts without exposing internal Modulith implementation.

Resource Ownership Model

flowchart TB
    Client[Mobile, Web, AIOS, or Integration Consumer]
    Resource[Domain-Owned API Resource]
    Command[Command Responsibility]
    Query[Query Responsibility]
    App[Owning Application Service]
    Domain[Owning Domain Module]

    Client --> Resource
    Resource --> Command
    Resource --> Query
    Command --> App
    Query --> App
    App --> Domain

Resource Rules

Rule	Requirement
Resources use business language	Resource names should reflect Domain language, not database tables or UI widgets.
Resources are domain-owned	The Domain that owns the concept owns the API boundary.
Commands change state	Command responsibilities create, update, transition, approve, submit, cancel, or otherwise change business state.
Queries read state	Query responsibilities retrieve lists, details, summaries, projections, or dashboards without changing state.
Workflows are explicit	Workflow transitions must be represented as governed business actions, not raw state field updates.
References do not imply ownership	A resource may reference another Domain by identifier without duplicating that Domain's facts.

Context Requirements

Context	Requirement
Tenant context	Required for tenant-scoped APIs and validated before business work.
Organization context	Required for organization-scoped resources and checked against tenant membership.
Actor context	Required for audit, authorization, approvals, and AIOS tool calls.
Correlation context	Required where a request participates in a workflow, integration, or event chain.
Entitlement context	Required where subscription plan, limits, or feature access affects behavior.

Domain Resource Areas

Domain	Resource Area Examples
Identity	memberships, roles, permissions, sessions, API keys.
Organization	organizations, tenant context, teams, operating profile.
Compliance	requirements, evidence, verifications, expiries, readiness.
Opportunity	opportunities, matches, saved opportunities, deadlines.
Bid	bid workspaces, bid tasks, bid documents, approvals.
Contract	contracts, milestones, delivery records, invoices, closeout.
Supplier	suppliers, quotes, relationships, trust state, performance.
Marketplace	listings, supplier needs, quote requests, marketplace matches.
Funding	funding needs, applications, offers, repayment context.
Learning	courses, lessons, progress, certificates, learning paths.
Intelligence	AI tasks, reasoning records, explanations, memory workflows.
Notification	preferences, notification requests, reminders, delivery history.
Analytics	dashboards, reports, KPI snapshots, metric summaries.
Billing	plans, subscriptions, invoices, payment state, entitlements.
Administration	feature flags, platform policies, support actions, audit reviews.

Non-Implementation Boundary

This document does not define final resource names, endpoint paths, payload fields, HTTP methods, or response schemas.