The
apps/maat/area: ten Nx application projects making up Maat, the Ghana-focused conglomerate / business-operations domain — five real Next.js operator frontends, one fully-built Hono API gateway, and four reserved service scaffolds.
What this area is#
Maat is the business-operations and portfolio-management domain for a Ghanaian
conglomerate. Its "companies" are themselves named after deities used elsewhere
in the monorepo — ASASE (AgriTech), FREYA (Logistics), CYBELE (Real
Estate), BRIGID (Steel/Manufacturing), SARASWATI (R&D/IP), IRIS (AI), and
AJE (Blockchain) — and the apps here are the tools an operator, strategist,
analyst, or investor uses to run that portfolio. Every project carries the
scope:maat Nx tag.
The area splits into three clearly different tiers. The first is a set of five
Next.js web frontends (@maat/dashboard's project is maat-dashboard-app,
plus @maat/agent-console, @maat/intel, @maat/investor, @maat/war-room),
each on its own dev port (3055–3059) and each tagged platform:web. These are
genuinely implemented App-Router apps: they pair real domain-specific financial
computation — DCF projection (apps/maat/war-room/src/lib/scenario-engine.ts),
Herfindahl-Hirschman concentration plus blended-IRR/NPV capital allocation
(apps/maat/war-room/src/lib/capital-allocation.ts), and a bisection-solver
NPV/IRR investment simulator (apps/maat/investor/src/lib/simulation-data.ts) —
with curated, in-process seed data (the src/lib/*-data.ts functions return
realistic Ghana-market fixtures rather than reading a live database).
The second tier is one real backend service, maat-api-gateway-app
(apps/maat/api-gateway, tagged layer:app). It is a fully-built Hono gateway
— JWT auth, RBAC, rate limiting, API versioning, an audit trail,
OpenAPI/Swagger, and a realtime WebSocket fan-out server — fronting eleven
logical upstream domain services (intelligence, strategy, agents,
finance, supply-chain, digital-twin, compliance, knowledge,
dashboard, simulation, worker). The third tier is four reserved service
scaffolds (maat-agents-app, maat-intelligence-app, maat-simulation-app,
maat-worker-app): each is just a .gitkeep plus a one-line
bootstrap<name>() in src/index.ts that returns an "... initialized"
string. They are honest placeholders for the upstream services the gateway is
configured to route to, not implemented runtimes.
How it fits the wider system#
The frontends are operator-facing and, today, largely self-contained: each reads
its own in-process fixture libraries and computes results client/server-side,
with the dashboard acting as the hub — the other four apps' nav components
(ConsoleNav, IntelNav, InvestorNav, WarRoomNav) link back to
http://localhost:3055. The only outbound network seam in the frontends is the
dashboard's own src/app/api/auth/login/route.ts, which optionally verifies
credentials against a configured MAAT_IDP_VERIFY_URL; the frontends do not
yet call the Maat API gateway. The gateway, in turn, is the intended edge for
the eleven domain services — four of which exist here only as scaffolds — so the
end-to-end "frontend → gateway → service" path is partially wired: the edge
layer and the UIs are real, the service backends behind the gateway are mostly
not yet built in this repo. Walk the dependency edges on any node below to see
exactly what it imports.
Entity catalog (10)#
The 10 tracked Nx projects in maat, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 10 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
app (5)#
A scaffold, honestly labelled (apps/maat/agents, project
maat-agents-app, tagged layer:app). The only real source is src/index.ts,
which exports bootstrapagents() returning the string
'maat-agents-app initialized', alongside a .gitkeep and the standard
tsconfig/vitest boilerplate. It reserves the slot for the agents upstream
domain service the API gateway is configured to dispatch to (/api/v1/agents),
but no agent-orchestration logic is implemented here yet.
The real edge service for the Maat domain (apps/maat/api-gateway, tagged
layer:app). src/app.ts builds a Hono application with Bearer-JWT
authentication (jsonwebtoken, HS256), a 23-value RBAC permission enum
(MaatPermissionSchema) enforced per-route via requirePermission, and an
organization-isolation check (ensureOrganizationAccess). It composes real
middleware: per-organization/user/agent sliding-window rate limiting backed by a
Redis pipeline (src/middleware/rate-limit.ts), RFC-8594 Sunset/Deprecation
API versioning (src/middleware/api-versioning.ts), request/response audit
logging with an in-memory default trail
(src/middleware/request-response-logging.ts), a programmatically-generated
OpenAPI 3.1 spec plus Swagger UI at /api/docs (src/openapi/spec.ts), and a
realtime WebSocket fan-out server with dashboard/agents/market-alerts/
simulation channels (src/realtime/websocket-server.ts). It registers eleven
domain-service routers from DEFAULT_DOMAIN_SERVICE_ROUTES; note that each
router's /dispatch validates and resolves the upstream URL and returns 202
accepted (and /health reports the route as "registered") rather than
reverse-proxying the request body through — the auth, RBAC, and routing surfaces
are complete, true upstream forwarding is not yet performed. Real tests exist
(src/app.spec.ts, src/realtime/websocket-server.spec.ts).
A scaffold (apps/maat/intelligence, project maat-intelligence-app,
tagged layer:app). Real source is limited to src/index.ts exporting
bootstrapintelligence() returning 'maat-intelligence-app initialized', plus
a .gitkeep and tsconfig/vitest boilerplate. It reserves the backend
intelligence domain service (/api/v1/intelligence in the gateway); note this
is distinct from the @maat/intel frontend, which is the implemented UI. No
intelligence-pipeline logic is implemented in this scaffold.
A scaffold (apps/maat/simulation, project maat-simulation-app, tagged
layer:app). The only real source is src/index.ts exporting
bootstrapsimulation() returning 'maat-simulation-app initialized', alongside
.gitkeep and standard config. It reserves the simulation upstream domain
service the gateway routes to (/api/v1/simulation, also a realtime
simulation channel); the actual heavy simulation engine is not implemented
here. (The investor and war-room frontends contain their own in-process
simulation math; this service backend remains a placeholder.)
A scaffold (apps/maat/worker, project maat-worker-app, tagged
layer:app). Real source is just src/index.ts exporting bootstrapworker()
returning 'maat-worker-app initialized', plus .gitkeep and tsconfig/vitest
boilerplate. It reserves the worker background-processing service the gateway
exposes (/api/v1/worker, worker:read/worker:write permissions); no
job/queue worker runtime is implemented here yet.
unclassified (5)#
The agent-fleet operations console (apps/maat/agent-console, dev port 3058). A
real Next.js App-Router app with a (console) route group covering fleet,
tasks, approvals, conversations, and analytics, backed by typed views
(AgentFleetView, TaskTreeView, ApprovalsView, ConversationView,
AgentAnalyticsView). Its data comes from in-process fixtures in
src/lib/agent-data.ts — getAgents() returns richly-typed agent records
(status, capabilities, dependency edges, and per-agent metrics like
successRatePct, p99LatencyMs, tokensUsedK) defined by
src/types/agent.ts. Curated seed data, not a live agent runtime, but the UI
and types are fully implemented.
The competitive-intelligence browser (apps/maat/intel, dev port 3057). A real
Next.js app whose (intel) route group covers landscape, news, pricing,
regulatory, and market sizing, rendered by views such as
CompetitiveLandscapeView, PriceMonitorView, RegulatoryTrackerView, and
MarketSizingView. The domain types in src/types/intel.ts model competitors,
threat levels, and strategic groups against the seven portfolio companies, and
src/lib/market-sizing-data.ts supplies TAM/SAM/SOM models with
Conservative/Base/Optimistic scenarios (Ghana-specific assumptions and five-year
CAGRs). Implemented UI and types over curated intelligence fixtures.
The investor / diaspora portal (apps/maat/investor, dev port 3059). A real
Next.js app with a (portal) route group covering dashboard, explore,
onboard (the DiasporaPortal), portfolio, and simulate, with components
like InvestorDashboard, BusinessUnitExplorer, InvestmentSimulator, and
InvestmentTierSelector. Its standout is genuine financial logic:
src/lib/simulation-data.ts implements npv() and a bisection-method irr()
solver and builds BEAR/BASE/BULL scenarios with annual cash flows, MOIC, and
payback — real computation, not hardcoded outputs — over investment-tier and
business-unit fixtures.
The strategy war room (apps/maat/war-room, dev port 3056) — the most
computation-heavy frontend. Its (war-room) route group covers
strategy-canvas, scenario, capital, market-entry, and synergies. It
carries two real engines: src/lib/scenario-engine.ts projects five-year DCF
financials from scenario variables using Ghana macro constants (25% corporate
tax, 21% WACC, 5% terminal growth) and computes scenario comparisons, and
src/lib/capital-allocation.ts computes the Herfindahl-Hirschman concentration
index, weighted blended IRR from per-company sector IRR expectations, and
WACC-discounted portfolio NPV. Blue Ocean strategy canvases and synergy/market-
entry data live in sibling src/lib/*-data.ts fixtures. Fully-implemented UI
plus real strategic-finance math.
The executive dashboard and the area's hub app (apps/maat/dashboard, package
@maat/dashboard, dev port 3055). The most fully-built frontend: it has real
JWT session auth using jose (src/lib/auth.ts signs an HS256 maat_session
httpOnly cookie with an 8-hour expiry), Next middleware (src/middleware.ts),
and login/logout API routes — src/app/api/auth/login/route.ts optionally
verifies against an external MAAT_IDP_VERIFY_URL. Its (dashboard) route
group covers portfolio, per-company drill-down (company/[companyId]),
alerts, and a layout-builder, with components like PortfolioOverview,
RiskRadarPanel, StrategicInitiativesPanel, and CompanyDrillDown. Financial
and company data come from in-process fixtures (src/lib/company-data.ts,
src/lib/portfolio-data.ts; portfolio-financials.ts simply re-exports
COMPANY_FINANCIALS).