Maat Domain — Technical Specifications

Maat — Portfolio Intelligence and Business Management Platform

This document specifies what is implemented in the Maat domain. It is grounded in the source under libs/maat/*, apps/maat/*, and libs/contracts/maat/. Every entity, field, enum value, event, endpoint, permission, and count below was read from source: libs/maat/core/src/ {organization,event-bus,redis-namespace}.ts, libs/maat/*/src/index.ts, libs/maat/finance/src/v2-persistence-ledger.ts, libs/maat/strategy/src/v2-fighting-game-live-ops-calendar.ts, libs/maat/dashboard/src/v2-balance-dashboard.ts, libs/maat/negotiation-intelligence/src/procurement-program.ts, libs/maat/knowledge/src/knowledge-graph-neo4j-schema.ts, libs/maat/sdk/src/typed-client.ts, apps/maat/api-gateway/src/{app,openapi/spec,middleware/api-versioning, realtime/websocket-server}.ts, and the apps/maat/* route trees. Where a capability is present only as a scaffold or is named in a phase backlog, it is labelled accordingly.

1. Domain Object Model (@maat/core)#

The foundational types live in libs/maat/core/src/organization.ts. This single file defines the entire shared domain vocabulary for the Maat platform: branded ID types that prevent accidental cross-type assignment, frozen enum value arrays, Zod schemas for every entity, and a complete set of constructor, serializer, and type guard functions. There is no ORM — all entities are in-memory value objects that can be validated, constructed, and serialized without a database.

For each entity, organization.ts follows a consistent pattern:

• A *Draft interface accepts loosely typed inputs (strings, partial objects).
• create<Entity>(draft) validates and normalises the draft, throwing on invalid input.
• create<Entity>WithDefaults(overrides?) deep-merges a DeepPartial over a built-in default object, making test setup concise.
• serialize<Entity>(value) / deserialize<Entity>(serialized) provide JSON round-trip helpers.
• is<Entity>(value) is an unknown-narrowing type guard.

1.1 Branded Identifier Types#

To prevent accidental cross-type mixing at compile time (passing an AgentId where an OrganizationId is expected), every entity identifier is a branded string type. Each type enforces a known prefix pattern and has a dedicated constructor function. The table below lists the 13 entity ID types and their regex patterns, all case-insensitive.

organization.ts defines a Brand<T, B> helper and these branded string IDs, each with a regex pattern and a create*Id constructor:

ISODateString (YYYY-MM-DD) and ISODateTimeString (UTC ISO-8601) are also branded; isISODateString, createISODateString, isISODateTimeString, and createISODateTimeString validate and construct them.

1.2 Enums and Literal-Union Value Arrays#

Rather than TypeScript enum declarations, every enumerated set is expressed as a frozen *_VALUES as const array with a derived union type. This pattern makes the full value set available at runtime (for validation, UI dropdowns, and API responses) while also providing compile-time type narrowing.

The following table lists all value arrays and their members.

1.3 Core Entities#

The 15 root entities are Organization, OperatingCompany, BusinessUnit, Market, Competitor, Project, KPI, Regulation, Risk, Agent, Scenario, Dashboard, Alert, AuditEvent, and Synergy. Each has a matching *Draft interface (loosely typed inputs accepted by the create* constructor) and an exported Zod schema. The detailed field specifications follow.

Organization#

The top-level entity representing the holding group that owns the portfolio companies.

OperatingCompany#

Represents one of the seven portfolio companies. Captures Ghana-specific regulatory identifiers (GRA TIN, SSNIT employer number) alongside standard company metadata, reflecting the platform's Ghana-first compliance posture.

BusinessUnit#

A division within an operating company, with its own product lines, factory locations, P&L summary, and workforce count.

Fields: id, parentCompanyId, name, graTaxIdentificationNumber, ssnitEmployerNumber, productLines[] (name, category, annualOutputUnits), factoryLocations[] (siteCode, countryCode, region, city, primaryProducts[]), employeeCount, capacityUtilizationPercent, and profitAndLossSummary (currencyCode, fiscalYear, revenue, costOfGoodsSold, grossProfit, operatingExpenses, operatingProfit, netProfit).

Market#

Describes a market segment that portfolio companies operate in or are evaluating for entry, including size estimates (TAM/SAM/SOM) and a regulatory complexity index.

Fields: id, name, geographicRegion, sectorClassification, sizeEstimates (currencyCode, referenceYear, tam, sam, som), annualGrowthRatePercent, competitiveIntensityScore, regulatoryComplexityIndex.

Competitor#

Tracks a named competitor with its market share, strengths, weaknesses, a timestamped timeline of recent moves, a threat level, and an intelligence freshness timestamp so stale competitive data is always visible.

Fields: id, name, marketSharePercent, strengths[], weaknesses[], recentMovesTimeline[] (happenedAt, headline, summary), threatLevel, intelligenceFreshnessTimestamp.

Project#

A tracked initiative owned by a business unit, with budget allocation, actual spend, milestones, assigned agents, and a reference to the risk register.

Fields: id, owningBusinessUnitId, name, description, status, budgetAllocation (currencyCode, amount), actualSpend, timelineMilestones[] (milestoneId, name, targetDate, optional completionDate), assignedAgents[] (agentId, role, allocationPercent), riskRegisterReference.

KPI#

A Key Performance Indicator with a target value, actual value, measurement frequency, trend direction, and a set of threshold alerts that fire when the metric crosses configured boundaries.

Fields: id, name, description, metricType, targetValue (value, unit), actualValue, measurementFrequency, trendDirection, thresholdAlerts[] (alertId, thresholdValue, comparator, severity, message), responsibleBusinessUnitId.

Regulation#

A regulatory requirement from a specific body, in a specific jurisdiction, with compliance requirements, associated penalties, and a list of affected business units. Note that Regulation has no branded ID — it is identified by jurisdictionCode + regulationIdentifier.

Fields: jurisdiction, regulatoryBodyName, regulationIdentifier, effectiveDate, complianceRequirements[] (requirementId, description, isMandatory, optional dueDate), penaltyStructure (optional currencyCode, optional min/max monetary penalty, nonMonetaryPenalties[]), affectedBusinessUnitIds[].

Risk#

A risk entry in a risk register, with a composite risk score derived from likelihood and impact scores, mitigation strategies, an owner reference, and a review schedule with a next-review date.

Fields: id, category, likelihoodScore, impactScore, compositeRiskScore, mitigationStrategies[], ownerReference (ownerId, ownerName, ownerRole), reviewSchedule (cadence, nextReviewDate, optional lastReviewedDate).

Agent#

An AI agent registration record. Each agent has a class (strategy, engineering, finance, operations, research, or compliance), a capability list validated against the AGENT_CAPABILITY_MATRIX, assigned tools, a memory context window size, a performance score, and a current task queue.

Fields: id, agentClass, name, capabilities[], assignedTools[], memoryContextWindow, performanceScore, currentTaskQueue[] (AgentTaskQueueItem: taskId, title, priority, status). The constructor checks each capability against AGENT_CAPABILITY_MATRIX, a per-AgentClass map of allowed capability strings.

Scenario#

A named simulation scenario with probabilistic weighting, outcome projections (a record of metric names to numeric values), and sensitivity parameters that bound the key assumptions.

Fields: id, name, description, scenarioCategory, assumptions[], timeHorizonMonths, probabilityWeight, simulatedOutcomes (record of string → number), sensitivityParameters[] (parameterName, baseValue, minimumValue, maximumValue).

Dashboard#

A configurable dashboard entity owned by a user or agent, with a grid or freeform layout, widget definitions with pixel positions, data-source bindings, refresh interval, and per-subject access permissions.

Fields: id, ownerReference (ownerId, ownerType, displayName), layoutConfiguration (layoutType, columns, rowHeight), widgetDefinitions[] (widgetId, widgetType, title, position {x,y,width,height}), dataSourceBindings[] (bindingId, widgetId, sourceKey, mode), refreshIntervalSeconds, accessPermissions[] (subjectType, subjectId, permissionLevel), lastViewedTimestamp.

Alert#

A system alert representing a condition requiring attention, with an escalation chain that automatically escalates to successively higher-level targets after configurable timeout windows.

Fields: id, severity, category, title, description, sourceSystem, affectedEntities[] (entityType, entityId), recommendedActions[] (actionId, description, priority, optional ownerId), acknowledgmentStatus, escalationChain[] (level, target, channel, triggerAfterMinutes).

AuditEvent#

An immutable audit record capturing who did what to which entity, with before/after state snapshots, a compliance classification, and a correlation ID for distributed tracing.

Fields: id, eventType, actor (actorType, actorId, optional actorDisplayName), targetEntity (entityType, entityId, optional entityName), actionPerformed, previousStateSnapshot, newStateSnapshot, timestamp, correlationId, complianceClassification.

Synergy#

A quantified inter-company synergy opportunity, linking a source business unit to a target business unit with an estimated annual value, a realization timeline, a probability score, and prerequisite dependencies. Note that Synergy has no branded ID.

Fields: sourceBusinessUnitId, targetBusinessUnitId, category, estimatedAnnualValue (currencyCode, amount, referenceFiscalYear), realizationTimeline (plannedStartDate, targetRealizationDate), probabilityScore, dependencyPrerequisites[] (code, description).

1.4 Constructors, Serialization, and Type Guards#

For each of the 15 entities, organization.ts exports the following — all must be present when adding a new entity:

• create<Entity>(draft) — validates and normalises a *Draft, throwing on invalid input;
• create<Entity>WithDefaults(overrides?) — deep-merges a DeepPartial over a built-in default object;
• serialize<Entity>(value) / deserialize<Entity>(serialized) — JSON round-trip helpers;
• is<Entity>(value) — unknown-narrowing type guard.

The Ghana-identifier schemas GhanaCompanyRegistrationNumberSchema, GRATaxIdentificationNumberSchema, and SSNITEmployerNumberSchema are exported for reuse by any library that needs to validate these identifiers independently.

2. Domain Event System (@maat/core)#

Defined in libs/maat/core/src/event-bus.ts. There is no Redis-backed bus; the implementation is a typed in-process bus. Events are the mechanism by which domain activities (market signals, agent completions, strategy decisions, compliance alerts, simulation progress) notify other parts of the system without creating direct library dependencies between them.

2.1 Event Types#

All domain events conform to exactly five types, each with its own Zod payload schema. MaatDomainEventTypeSchema is a Zod enum of these five values:

2.2 Base Envelope#

Every event extends a shared base envelope, ensuring consistent tracing metadata regardless of event type. BaseMaatEventSchema requires: eventId (UUID), eventType, schemaVersion (literal 1), organizationId, source, correlationId, optional causationId, optional traceId, and occurredAt (ISO-8601 with offset). MaatDomainEventSchema is a discriminated union on eventType.

2.3 Event Payloads#

The five event payload schemas carry the following domain-specific fields. Note the bounded numeric fields (confidence, impact scores) and the discriminated status enums — these enforce domain invariants at the schema level.

2.4 Bus API#

The InMemoryMaatEventBus class and its supporting utilities form the complete bus API:

• MAAT_EVENT_SCHEMAS — record mapping each event type to its Zod schema.
• parseMaatDomainEvent(event) — validates an unknown payload, routing by eventType to the matching schema.
• createMaatEvent(draft) — fills eventId (randomUUID()), schemaVersion (1), and occurredAt (new Date().toISOString()) defaults, then validates.
• InMemoryMaatEventBus — class with publish(input) (parses then dispatches), subscribe(eventType, handler), subscribeAll(handler), getSubscriberCount(eventType?), and clearSubscriptions(). Each subscribe* call returns an unsubscribe function. Handlers run via Promise.allSettled; if any reject, dispatch throws an AggregateError.

3. Redis Namespace Builder (@maat/core)#

libs/maat/core/src/redis-namespace.ts provides a pure key-string builder; it does not open a Redis connection. Its purpose is to centralize the key-prefix convention so that all services are guaranteed to use consistent, non-colliding namespace strings when a Redis integration is eventually wired in.

createMaatRedisNamespacePrefixes(options?) accepts basePrefix (default maat), environment, and separator (default :), and returns MaatRedisNamespacePrefixes. When an environment is provided, the root prefix becomes maat:<environment> — keeping dev, staging, and production namespaces separate on a shared Redis instance.

createMaatRedisKeyBuilder(prefixes?) returns a MaatRedisKeyBuilder with agentState, intelligenceCache, strategyResult, dashboardState, and rateLimit key-composing functions. assertUniqueNamespacePrefixes(prefixes) throws if any two prefixes collide. MAAT_REDIS_NAMESPACES and MAAT_REDIS_KEYS are the default-configured singletons.

4. Library Surface#

libs/maat/ contains 19 libraries, all published as @maat/<name>. Each library's src/index.ts exports a <NAME>_LIBRARY package-name constant plus the per-feature modules below. The implementation modules are pure TypeScript; no library imports a database driver (pg, drizzle, neo4j-driver, redis/ioredis). The only external runtime SDK is @anthropic-ai/sdk, imported by @maat/intelligence in world-model-simulator.ts and report-generation-pipeline.ts.

The table below shows status and module counts as read from each library's src/index.ts. A "scaffold" status means the library exists with a project.json and package.json but its source files contain minimal stubs — it is a placeholder for planned work, not a reduced-size implementation.

Note: @maat/dashboard is not a general dashboard aggregation layer. Its only source file beyond the V2 contract is a .gitkeep. Dashboard entity types (Dashboard, widgets, layouts, permissions) live in @maat/core.

4.1 @maat/negotiation-intelligence — Procurement Program (Phase 179.7.1)#

Defined in negotiation-intelligence/src/procurement-program.ts. This module seeds the Concordia shared bargaining substrate with Maat's procurement-program configuration: the tracks Maat negotiates under, the levers it uses, and the approval thresholds that gate high-value decisions. The agent mediation behaviour itself is still planned for a later phase.

It exports:

• ProcurementTrackSchema — enum of procurement tracks.
• ProcurementLeverSchema — enum of negotiation levers.
• ApprovalThresholdSchema — object with an approval threshold definition.
• ProcurementProgramSchema — the full program object.
• findApprovalThreshold(...) — selects the threshold applicable to a value.
• toMaatExtensionDefaults(program) — projects a program into Concordia extension defaults.

5. API Gateway (apps/maat/api-gateway)#

apps/maat/api-gateway is a Hono application (not Fastify). It is a JWT-authenticated reverse-dispatch gateway that sits in front of per-domain upstream services, providing a single authenticated entry point for all Maat API consumers. Rather than each downstream service managing its own auth and organization access enforcement, the gateway handles both centrally. Source: apps/maat/api-gateway/src/app.ts.

5.1 Authentication and Authorization#

• createAuthMiddleware verifies a Bearer JWT with HS256 using MAAT_JWT_SECRET (falls back to a development secret).
• MaatJwtClaimsSchema requires sub, orgId, roles[], permissions[], and optional exp/iat.
• MaatPermissionSchema enumerates 23 permission strings: gateway:admin plus read/write pairs for intelligence, strategy, agents, finance, supply-chain, digital-twin, compliance, knowledge, dashboard, simulation, and worker.
• requirePermission(permission) allows the request if the caller holds the permission or the platform-admin role.
• ensureOrganizationAccess rejects cross-org access unless the caller is a platform-admin.

5.2 Routes#

The gateway exposes a set of infrastructure routes directly, plus domain-service proxy routes for each of the 11 registered services. The infrastructure routes are:

Each of the 11 domain services additionally mounts a router under its base path (/api/v1/intelligence, /api/v1/strategy, /api/v1/agents, /api/v1/finance, /api/v1/supply-chain, /api/v1/digital-twin, /api/v1/compliance, /api/v1/knowledge, /api/v1/dashboard, /api/v1/simulation, /api/v1/worker) exposing:

• GET /health — service registration status (requires the read permission);
• POST /dispatch — forwards an organizationId/path/method/query/body request to the upstream service URL (requires the write permission). Upstream URLs come from MAAT_<SERVICE>_SERVICE_URL env vars, defaulting to http://maat-<service>:3000.

5.3 Middleware#

apps/maat/api-gateway/src/middleware/ provides three middleware modules:

• api-versioning.ts — MAAT_API_VERSIONS (currently only v1, CURRENT_API_VERSION = 'v1'); attaches X-Api-Version* headers, emits Deprecation/Sunset headers for deprecated versions, and rejects unknown versions when enforceKnownVersions is set.
• rate-limit.ts — createMaatRateLimitMiddleware for /api/v1/*.
• request-response-logging.ts — logging middleware plus InMemoryMaatRequestAuditTrail, an in-memory audit store with a filterable list({ limit, organizationId, outcome }).

5.4 Realtime WebSocket Server#

apps/maat/api-gateway/src/realtime/websocket-server.ts defines MaatRealtimeWebSocketServer. This server handles live data delivery for the five Next.js web apps — pushing dashboard updates, agent status changes, market alerts, and simulation progress without requiring each app to poll. RealtimeChannelSchema enumerates four channels: dashboard, agents, market-alerts, simulation. Clients send subscribe/unsubscribe/heartbeat commands; rooms are keyed channel:org[:entity]. Org-scoped access is enforced per room. Broadcast methods: broadcastDashboardUpdate, broadcastAgentStatus, broadcastMarketAlert, broadcastSimulationProgress.

6. SDK (@maat/sdk)#

libs/maat/sdk/src/typed-client.ts provides MaatClient, a typed client whose transport is a pluggable HttpAdapter. The SDK is designed to work in tests and integration contexts without a live server: when no adapter is supplied the client falls back to MockHttpAdapter, giving consumers type-safe request/response shapes even before the real backend is wired.

• MaatClientConfig — baseUrl, apiKey, environment (production/staging/development/local), optional defaultCurrency (default GHS), defaultTimezone (default Africa/Accra), timeoutMs (default 30000), maxRetries (default 3), modules, and debug.
• Sub-clients on MaatClient: companies (CompanyClient), finance (FinanceClient), risks (RiskClient), scenarios (ScenarioClient), reporting (ReportingClient).
• forCompany(companyId) returns a ScopedCompanyClient; ping() probes /api/v1/health.
• Response envelopes: ApiResponse<T> (data + meta) and PaginatedResponse<T> (adds pagination). FilterClause supports operators eq, neq, gt, gte, lt, lte, in, contains, startsWith.

The other SDK modules are cli-tool, react-components, webhook-manager, api-key-manager, batch-operations, sse-streaming, plugin-architecture, offline-mode, and sdk-docs-generator.

7. V2 Cross-Domain Contracts#

Maat owns three contracts that serve the separate V2 (fighting-game) program. They are implemented inside the Maat libraries because Maat provides the business authority — financial transaction governance, season calendar, and balance analytics — even in the context of a competitive game. A key invariant of all three contracts is that rollback frames must never call Maat services: real-time combat simulation is deterministic and must not depend on external service availability.

7.1 Finance Persistence Ledger — @maat/finance/v2-persistence-ledger#

This subsection defines the V2 Persistence Ledger Contract: Maat finance is the single source of truth for every V2 currency mutation, and the engine holds only a reconciling cache. The TypeScript authority lives in libs/maat/finance/src/v2-persistence-ledger.ts, the V2 service wrapper is published as @v2/maat-finance-ledger (depending on @maat/finance at workspace:*), and the in-engine policy struct is FV2MaatFinanceLedgerPolicy in V2/ue/Source/V2Persistence/Public/V2PersistenceTypes.h.

v2-persistence-ledger.ts exports V2_MAAT_FINANCE_LEDGER_CONTRACT_ID (v2.persistence.maat-finance-ledger.v1) and V2_MAAT_FINANCE_OFFLINE_CACHE_MODE (v2-engine-ledger-cache-reconcile-on-sync).

Transaction types are grant, spend, refund, adjust, migration. Decision reasons include approved-online-authority, approved-offline-cache, invalid-transaction-shape, region-price-mismatch, regulatory-cap-exceeded, refund-reference-required, and refund-window-expired. V2MaatFinanceRegionalPricingPolicy carries region-aware PPP pricing and regulatory transaction/daily-spend caps.

Required behaviour:

1. Spend decisions verify region-aware PPP pricing.
2. Spend and refund decisions check regulatory caps and refund windows before the entry is mirrored.
3. Approved offline entries carry a Maat decision id and reconcile on next online sync.
4. Rollback frames never call Maat finance services.

The Unreal side mirrors this in FV2MaatFinanceLedgerPolicy, whose SourceOfTruthPackageName defaults to @maat/finance and whose bRequiresOnlineReconciliation flag marks cached offline entries that must be re-validated against Maat on the next online sync. ApplyMaatFinanceTransaction consumes the policy to apply region-priced spend/refund deltas to the engine currency ledger; it never participates in deterministic combat and never influences rollback. The reciprocal @v2/maat-finance-ledger service composes @maat/finance as its source of truth (sourceOfTruthPackageName: MAAT_FINANCE_PACKAGE_NAME), flags inEngineLedgerCache: true and reconcileOnNextOnlineSync: true, and pins mayInfluenceRollback: false.

7.2 Live-Ops Calendar — @maat/strategy/v2-fighting-game-live-ops-calendar#

This subsection defines the V2 Fighting-Game Live-Ops Calendar Contract, served to the V2 program through the @v2/maat-live-service-calendar package (depending on @maat/strategy at workspace:*). Maat strategy is authoritative for the season calendar and Crown Points economy; the V2 wrapper marks standaloneV2LiveCalendarReplaced: true, asserting that there is no separate V2 calendar schema, and exposes the engine read hooks Rank.GetCrownPoints and Esports.QualifyForFinals.

libs/maat/strategy/src/v2-fighting-game-live-ops-calendar.ts exports MAAT_V2_LIVE_OPS_CALENDAR_SOURCE_OF_TRUTH_ID, the Pro Circuit tier values (MAAT_V2_PRO_CIRCUIT_TIER_VALUES), and the live-ops event kinds (MAAT_V2_LIVE_OPS_EVENT_KIND_VALUES). Types include MaatV2LiveOpsSeason, MaatV2ProCircuitEvent, MaatV2AnniversaryEvent, MaatV2CharityEvent, MaatV2BalanceRampWindow, and MaatV2CrownPointsRule. The functions calculateMaatV2CrownPoints(input) and buildMaatV2FightingGameLiveOpsCalendar(...) compute Crown Points and assemble the calendar. Maat owns seasons, ranked-season windows, Crown Points pool sizing and tier scoring, the Pro Circuit calendar, and anniversary/charity/balance-ramp windows. Rollback frames never call the calendar.

7.3 Balance Dashboard — @maat/dashboard/v2-balance-dashboard#

This subsection defines the V2 Balance Dashboard Contract, exposed to the V2 program as @v2/maat-balance-dashboard. That service composes three Maat libraries — @maat/intelligence (trend and anomaly detection), @maat/dashboard (panel/manifest governance), and @maat/reporting (scorecards and operational KPI charts) — each pinned at workspace:*; it deliberately does not depend on @maat/analytics. The wrapper sets standaloneV2DashboardReplaced: true, confirming there is no standalone V2 balance dashboard, and pins mayInfluenceRollback: false.

libs/maat/dashboard/src/v2-balance-dashboard.ts exports MAAT_V2_BALANCE_DASHBOARD_ID (maat.v2.balance-dashboard) and buildMaatV2BalanceDashboardSurface(input). The contract declares the companion @maat/reporting and @maat/intelligence package names by reference; it does not import them. MAAT_V2_BALANCE_DASHBOARD_EVENT_TOPICS lists eight topics: v2.match.ended, v2.match.combat.move.used, v2.match.combat.damage.applied, v2.match.combat.attack.blocked, v2.match.combat.frame-data.drift, v2.match.balance.ab-result.published, v2.match.balance.ptb-signal.recorded, and v2.match.performance.frame-budget-exceeded. Panel kinds: pick-rate, win-rate, win-rate-on-block, frame-data-drift, hot-cold-heatmap, ab-publication, release-gate. The output is a dashboard/reporting artifact; it is off rollback and must not influence deterministic combat simulation.

8. Knowledge Graph Schema (@maat/knowledge)#

libs/maat/knowledge/src/knowledge-graph-neo4j-schema.ts defines an in-memory graph schema (TypeScript records and Zod validation; no neo4j-driver dependency). The schema is designed for a future Neo4j projection: every node record carries a neo4jLabel field, and relationship types are modelled to map directly onto Neo4j relationship labels.

The vocabulary is:

• KG_NODE_TYPE_VALUES: ORGANIZATION, PERSON, PRODUCT, MARKET, REGULATION, TECHNOLOGY, LOCATION, EVENT, CONCEPT.
• KG_RELATIONSHIP_TYPE_VALUES: COMPETES_WITH, SUPPLIES_TO, REGULATED_BY, LOCATED_IN, INVENTED_BY, PART_OF.
• KnowledgeGraphNodeRecord (nodeId, nodeType, neo4jLabel, properties, createdAt, updatedAt, version) and KnowledgeGraphRelationshipRecord model nodes and edges.

9. Frontend Applications#

apps/maat/ contains 11 application roots: 5 implemented Next.js web apps, 1 implemented Hono service app, and 4 bootstrap scaffold service apps.

9.1 Implemented Next.js Apps (5)#

Each app targets a distinct user persona: portfolio-level executives use the dashboard app, operations teams use agent-console, analysts use intel, investors use the investor portal, and strategists use the war room. Each runs on its own Next.js port (e.g. dashboard on 3055) and has build/start/lint/ typecheck/test Nx targets.

9.2 Implemented Service App (1)#

api-gateway (maat-api-gateway-app) — the Hono gateway described in §5.

9.3 Scaffold Service Apps (4)#

agents (maat-agents-app), intelligence (maat-intelligence-app), simulation (maat-simulation-app), and worker (maat-worker-app) each contain only a bootstrap<name>() function returning an "<name> initialized" string. They are placeholders for future deployable services.

10. Technology Stack#

The table below summarizes the technology choices for the domain. The most important entry for new contributors is the last row: there is no persistence layer wired in. All domain state lives in-memory. The Redis namespace and Neo4j schema modules are forward-looking contracts, not active connections.

There is no PostgreSQL, Drizzle, Neo4j driver, or Redis client wired into the domain. The "Redis namespace" and "Neo4j schema" modules produce keys and record shapes for a future datastore integration but do not connect to one.

11. Validation Rules#

The @maat/core Zod schemas enforce a set of domain invariants at construction time. These rules apply to all entities and must be respected in any code that creates or modifies Maat domain objects.

Entity-level rules:

• Strict objects — every entity schema uses .strict(), rejecting unknown keys.
• ID patterns — IDs must match their prefixed regex (§1.1).
• Currency — currencyCode must be a 3-letter ISO 4217 code; country codes must be 2-letter ISO codes.
• Percent fields — 0 ≤ value ≤ 100; probability/score fields — 0 ≤ value ≤ 1; fiscal years — integer 1900 ≤ year ≤ 9999.
• Ghana GH jurisdiction — a LegalEntityRegistration with jurisdictionCode === 'GH' must use a Ghana company registration number.
• Exactly one primary registration — LegalEntityStructure.registrations must contain exactly one entry with isPrimary === true.
• Board terms — a board member's termEndAt cannot precede appointedAt.
• Non-empty collections — Organization.operatingCompanies and LegalEntityStructure.registrations require at least one entry.
• Agent capabilities — createAgent rejects capabilities not listed for the agent's class in AGENT_CAPABILITY_MATRIX.

Event validation rules (enforced by event-bus.ts): eventId must be a UUID, schemaVersion must be the literal 1, occurredAt must be ISO-8601 with offset, confidence values are bounded 0–1, expectedImpactScore is bounded −100…100, and StrategyDecisionEvent.approvedBy requires at least one approver.

12. Acceptance Criteria#

A Maat change is acceptable when all of the following conditions hold:

1. New or changed @maat/core entities ship the full set — interface, *Draft, *_VALUES arrays for any new enum, Zod schema, create*, create*WithDefaults, serialize*/deserialize*, and is* — and are re-exported from index.ts.
2. Every schema is .strict() and every constructor throws on invalid input.
3. npx tsc --noEmit and npx vitest run pass in the affected library directory (Nx may be bypassed per repository policy).
4. New API gateway routes declare a MaatPermission, enforce ensureOrganizationAccess for org-scoped data, and are reflected in the generated OpenAPI spec.
5. New domain events extend BaseMaatEventSchema, are added to MaatDomainEventTypeSchema and MAAT_EVENT_SCHEMAS, and validate through parseMaatDomainEvent.
6. V2 contract changes preserve the rollback-exclusion and source-of-truth-ownership rules in §7.