# Maat Domain β€” Features and Capabilities Named after Maat (𓁦), the ancient Egyptian goddess of cosmic order, truth, balance, and justice β€” who weighs the hearts of the dead against her feather of truth in the Hall of Two Truths β€” Maat is the autonomous organization operating system for managing a multi-company portfolio of industrial and commercial businesses in West Africa and across the continent. Just as the goddess Maat maintained cosmic order by ensuring every action was weighed against its rightful measure, the Maat domain maintains organizational order by measuring every business dimension against its optimal state. Maat provides strategic intelligence, multi-agent AI orchestration, financial modeling, supply chain optimization, workforce planning, regulatory compliance, and a real-time organizational digital twin β€” enabling a single executive team to oversee a diverse portfolio of companies with the analytical depth of a hundred specialized advisors. The platform is purpose-built for the Ghanaian and West African business environment: its financial modeling incorporates mobile money and GHS/USD dynamics, its compliance registry covers all Ghanaian regulatory bodies, its supply chain intelligence is calibrated to ECOWAS trade routes and AfCFTA tariff schedules, and its labor market data reflects Ghanaian workforce conditions. The platform is implemented as **17 fully implemented domain libraries**, one partially implemented library (`@maat/negotiation-intelligence`, Phase 179 seed), and one V2-contract-only scaffold (`@maat/dashboard`). On the application side, five Next.js web apps and one Hono API gateway are implemented; four additional service app stubs (`agents`, `intelligence`, `simulation`, `worker`) are planned. --- ## At a Glance The table below maps each major capability area to the Maat module that delivers it. Each row corresponds to a detailed section in this document. | Capability Area | What Maat Provides | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Strategic intelligence | Porter's Five Forces, SWOT, BCG matrix, Blue Ocean, scenario simulation | | Financial modeling | DCF, LBO, IRR/NPV, pro forma financials, multi-currency consolidation | | Multi-agent AI | Specialized agents for strategy, finance, engineering, operations, research, compliance | | Digital twin | Real-time computational model of each portfolio company's organizational state | | Compliance | Ghana regulatory body registry, compliance calendar, gap analysis, ESG reporting | | Market intelligence | Competitor tracking, sentiment analysis, satellite imagery, NL2SQL queries | | Risk management | Monte Carlo simulation, VaR, political risk, climate risk, cybersecurity risk | | Supply chain | Supplier mapping, landed cost, AfCFTA optimization, ECOWAS CET tariff database | | Knowledge management | Knowledge graph (in-memory, Neo4j-projectable schema), graph-RAG engine, patent landscape, academic research monitoring | | Workforce | Org design modeling, skills gap analysis, succession planning, attrition prediction | | Portfolio companies | Asase (agriculture), Freya (luxury fashion), Cybele (construction), Brigid (manufacturing), Saraswati (R&D), Iris (AI Conversation β€” Maat portfolio company, distinct from the `@iris/*` Oshun platform domain), Aje (blockchain) | --- ## 1. Core Platform Foundation (`@maat/core`) The foundational layer providing domain-wide event infrastructure, organization type models, and Redis namespace management. Every other Maat module depends on the types, constants, and infrastructure defined here. This library defines the common vocabulary β€” branded identifiers, entity schemas, and event types β€” so that all other libraries can interoperate without circular dependencies. - **Domain event bus** β€” Typed, Zod-validated domain events for the five core event categories: `MarketIntelligenceEvent` (competitor signals, price movements, trend alerts), `AgentTaskEvent` (agent task lifecycle from dispatch through completion), `StrategyDecisionEvent` (recorded strategic decisions with rationale), `ComplianceAlertEvent` (regulatory deadline and gap alerts), and `SimulationStateEvent` (digital twin state changes). Events carry correlation IDs and trace IDs for distributed tracing across services. - **Organization type models** β€” Branded TypeScript types for `OrganizationId`, `OperatingCompanyId`, `BusinessUnitId`, `MarketId`, `CompetitorId`, `ProjectId`, `KPIId`, `RiskId`, `AgentId`, `ScenarioId`, `DashboardId`, `AlertId`, and `AuditEventId`, plus ISO date/datetime strings, preventing cross-type confusion at compile time. Zod-validated, `.strict()` schemas cover the eight legal entity types (holding company, conglomerate, private limited, public limited, partnership, cooperative, non-profit, state-owned), four legal structure models (single entity, holding with subsidiaries, multi-holding, federated), and the full set of 15 domain entities β€” each with a `create*` constructor, defaults helper, serializer pair, and type guard. - **Redis namespace management** β€” Centralized Redis key namespace builder producing consistent, collision-proof cache and state keys across all services. Namespace prefixes cover agent state, intelligence cache, strategy results, dashboard state, and rate limiting. Namespace options support environment-aware key prefixes (dev/staging/prod) with configurable separators. --- ## 2. AI Agent Orchestration (`@maat/agents`) Autonomous AI agents are the operational core of Maat β€” they perform continuous analysis, monitoring, and execution tasks across the portfolio companies, freeing human executives for strategic decisions. The `@maat/agents` library (28 modules) implements a complete multi-agent platform: agent registration, lifecycle, task orchestration, inter-agent communication, memory, performance tracking, and advanced AI infrastructure including a pure-TypeScript workflow graph engine and a federated learning framework. ### 2.1 Agent Architecture - **Specialized domain agents** β€” Dedicated agents for each expertise domain: strategy (competitive analysis, market entry, scenario planning), engineering (technical due diligence, systems assessment), finance (financial modeling, variance analysis, forecasting), operations (process optimization, capacity planning), research (market research, patent intelligence, competitive monitoring), and compliance (regulatory monitoring, gap analysis, filing preparation). - **Agent registry** β€” Central registry for discovering, configuring, and monitoring all agents. New agent types can be registered without modifying the core orchestration framework. - **Agent lifecycle management** β€” Full lifecycle from agent initialization through task execution to teardown, with health monitoring and automatic restart on failure. - **Agent pool management** β€” Connection pooling and concurrency management for high-throughput agent workloads. Agents can be instantiated in pools and load-balanced across tasks. ### 2.2 Task Orchestration - **Task decomposition** β€” Breaks complex business objectives into executable subtask graphs. "Analyze our competitive position in the construction market" decomposes into competitor identification β†’ data collection β†’ comparative analysis β†’ strategic positioning recommendation. - **Dependency graph execution** β€” Executes interdependent task graphs with correct ordering and parallelism. Tasks that can be parallelized run concurrently; tasks with dependencies wait for their prerequisites. - **Tool registry** β€” Extensible tool registry giving agents access to databases, external APIs, financial data providers, market data feeds, satellite imagery providers, and internal Maat subsystems. - **Inter-agent communication** β€” Structured protocol for agents to exchange context, results, and task delegation requests. An analyst agent can hand off a research finding to a strategy agent for interpretation. - **Agent memory system** β€” Persistent and working memory for agents to accumulate context across multi-session tasks. Long-running competitive analysis projects benefit from accumulated context about competitors discovered in prior sessions. - **Human-in-the-loop workflows** β€” Configurable escalation and approval gates for decisions requiring human judgment. Capital allocation decisions above a threshold always require human approval regardless of agent confidence. ### 2.3 Advanced AI Infrastructure - **LangGraph-style workflow engine** β€” Graph-based workflow orchestration for complex multi-step reasoning tasks that require dynamic branching and conditional logic, with checkpointed state and human-in-the-loop interrupt nodes. Implemented as a pure-TypeScript engine (LangGraph-style, not the LangGraph library itself). - **Reinforcement learning environment** β€” RL training environment for capital allocation decision optimization, allowing the capital allocation agent to improve through simulated deployment decisions. - **Federated learning framework** β€” Privacy-preserving distributed learning across portfolio company data. Companies can jointly improve shared models without exposing confidential company data to each other. - **Agent performance tracking** β€” Systematic measurement of agent task completion rates, prediction accuracy, latency, and cost per task. - **Agent feedback loops** β€” Continuous improvement system incorporating task outcome feedback back into agent configuration and model fine-tuning. - **Agent collaboration framework** β€” Multi-agent coordination for tasks requiring parallel specialist input: a market entry analysis might simultaneously run agents for regulatory analysis, competitive landscape, financial feasibility, and operational requirements. - **Agent observability dashboard** β€” Real-time visibility into agent activity queues, current tasks, completion rates, and error logs. --- ## 3. Strategic Intelligence and Analysis (`@maat/intelligence`, `@maat/strategy`) ### 3.1 Strategic Frameworks Standard strategic analysis frameworks are implemented as automated, data-driven engines that produce structured assessments rather than blank templates. A new engineer should understand these as real analytical computations, not just named modules β€” each framework is wired to live intelligence feeds and produces scored, explainable outputs. - **Porter's Five Forces analysis** β€” Automated competitive force analysis: bargaining power of suppliers and buyers, threat of new entrants, threat of substitutes, and competitive rivalry. Applied across all portfolio industries with data from market intelligence feeds. - **SWOT analysis engine** β€” Structured Strengths/Weaknesses/Opportunities/Threats assessment with AI-generated narrative insights that explain the implications of each factor. - **TAM/SAM/SOM calculator** β€” Total Addressable Market, Serviceable Addressable Market, and Serviceable Obtainable Market calculation using market sizing methodology. Outputs differ by estimation approach (top-down vs. bottom-up) to bracket uncertainty. - **BCG growth-share matrix** β€” Portfolio positioning on the Boston Consulting Group matrix (Stars, Cash Cows, Question Marks, Dogs) using growth rate and relative market share metrics. Updated continuously as financial data changes. - **Ansoff growth matrix** β€” Analysis of four growth strategies: market penetration (existing product, existing market), market development (existing product, new market), product development (new product, existing market), and diversification (new product, new market). Each strategy is assessed for risk and feasibility. - **Blue Ocean strategy canvas** β€” Value innovation mapping identifying which factors the industry competes on, which can be reduced or eliminated, and which new factors could create uncontested market space where competition is irrelevant. - **Market entry analysis** β€” Multi-factor market entry scoring with barriers analysis (capital requirements, regulatory requirements, established competitor responses), opportunity quantification, and timing assessment. - **Synergy valuation** β€” Quantifies cross-company synergies from shared resources, customer cross-selling opportunities, shared capabilities, and operational efficiencies across the portfolio. ### 3.2 Scenario Planning and Simulation - **Game theory analysis** β€” Strategic interaction modeling for competitor response scenarios and negotiation situations. Models Nash equilibria and best response strategies for competitive decisions. - **Monte Carlo scenario simulation** β€” Probabilistic simulation of business outcomes across thousands of scenarios. Produces probability distributions of outcomes rather than single point estimates, making uncertainty explicit. - **Sensitivity analysis** β€” Identifies the key variables that most impact business outcomes. If revenue is sensitive to one price assumption but robust to all cost assumptions, management attention should focus on pricing certainty. - **Stress testing** β€” Tests portfolio resilience against extreme economic shocks (40% currency devaluation), political shocks (election outcome changes), and market shocks (commodity price collapse). - **Scenario comparison engine** β€” Side-by-side comparison of alternative strategic scenarios across financial, operational, and strategic dimensions. ### 3.3 Portfolio Optimization - **Modern Portfolio Theory optimizer** β€” Applies Markowitz portfolio optimization to portfolio company allocation, maximizing risk-adjusted returns across the company mix. - **Dynamic capital reallocation** β€” Real-time capital reallocation recommendations as company performance data evolves. Identifies underperforming companies that should receive less capital and outperforming ones that could absorb more. - **Resource constraint optimizer** β€” Optimizes shared resource allocation (management time, shared services, capital) across simultaneous portfolio priorities. - **Strategic planning dashboard** β€” Aggregated view of strategic metrics, priorities, and progress across all portfolio companies in a single executive interface. --- ## 4. Financial Modeling and Capital Management (`@maat/finance`, `@maat/capital`) ### 4.1 Valuation and Financial Modeling - **Cash flow forecasting** β€” Multi-period cash flow forecasting with seasonality modeling (critical for agricultural businesses with harvest cycles) and growth rate modeling. - **Discounted cash flow (DCF) engine** β€” Full DCF valuation with WACC calculation (Weighted Average Cost of Capital), terminal value computation using both Gordon Growth and exit multiple methods, and sensitivity tables showing how valuation changes with different assumptions. - **Comparable company analysis** β€” Peer group selection and trading multiple benchmarking (EV/EBITDA, P/E, EV/Revenue) for private company valuation reference. - **Real options valuation** β€” Industrial real options models for valuing investment flexibility: the option to expand a facility, defer an investment, or abandon a project. - **IRR/NPV calculator** β€” Internal Rate of Return and Net Present Value calculations for investment decisions, including handling of irregular cash flows and partial-period returns. - **Leveraged buyout model builder** β€” Full LBO model with debt structuring (senior debt, mezzanine, equity), returns analysis (IRR, MoM), and exit scenario modeling under different valuation assumptions. ### 4.2 Financial Planning - **Pro forma income statement** β€” Forward-looking income statement generation with configurable revenue and cost driver assumptions. Multiple scenarios (base, bull, bear) generated simultaneously. - **Pro forma balance sheet** β€” Forward-looking balance sheet with financing structure, working capital modeling (days receivable, days payable, inventory turns), and liquidity projections. - **Revenue forecasting engine** β€” Revenue projection using multiple approaches: growth rate extrapolation, cohort analysis, market sizing, and unit economics build-up. - **Unit economics calculator** β€” Customer Lifetime Value, Customer Acquisition Cost, payback period, and contribution margin analysis per business unit and customer segment. - **Budget variance analysis** β€” Actual vs. budget and actual vs. forecast variance reporting with automated root cause attribution commentary. - **Financial ratio dashboard** β€” Profitability ratios (ROE, ROIC, EBITDA margin), liquidity ratios (current ratio, quick ratio), leverage ratios (debt/equity, interest coverage), and efficiency ratios (asset turnover, inventory turnover) across all portfolio companies. ### 4.3 Capital Allocation - **Black-Litterman model** β€” Bayesian asset allocation model that combines market equilibrium with portfolio manager views. Allows executives to incorporate qualitative judgments about company prospects while maintaining mathematical rigor. - **Milestone capital release** β€” Staged capital release tied to company performance milestones. Capital tranches are released when companies achieve defined operational or financial targets. - **Hurdle rate management** β€” Dynamic hurdle rate setting based on each company's risk profile, growth stage, industry, and current market conditions. - **Capital budgeting** β€” Long-term capital expenditure planning and project prioritization using NPV, IRR, and strategic fit scoring. - **Debt capacity analysis** β€” Maximum sustainable debt level analysis per company based on cash flow coverage, asset coverage, and covenant compliance modeling. - **Funding round analysis** β€” Dilution modeling, pre-money/post-money valuation calculation, and term sheet analysis for portfolio company equity raises. - **M&A evaluation** β€” Target screening, synergy modeling, and deal structuring for acquisition activity. ### 4.4 Ghana-Specific Financial Management The financial management capabilities in this section are specifically calibrated for the Ghanaian business environment, where GHS/USD exchange dynamics, GRA tax obligations, and government investment incentive structures create challenges that generic international financial tooling does not address. - **FX risk management** β€” Multi-currency exposure analysis (USD, GBP, EUR, ECOWAS currencies), hedging strategy assessment, and revaluation impact modeling. Critical for businesses with USD revenues but GHS cost bases. - **Multi-currency consolidation** β€” Consolidates financial results across companies reporting in different currencies using configured translation rates. - **Transfer pricing engine** β€” Intercompany pricing compliance and optimization for transactions between portfolio companies, ensuring compliance with Ghana Revenue Authority transfer pricing rules. - **Ghana tax optimization** β€” Ghana-specific tax planning incorporating investment incentives (Free Zones, Ghana Investment Promotion Centre benefits), double taxation treaty benefits, and sector-specific tax exemptions. - **Ghana tax calendar** β€” Automated regulatory filing deadline management for all Ghanaian tax obligations: corporate income tax, VAT, withholding tax, employee taxes. - **Diaspora investment modules** β€” Structured tools for diaspora investment vehicles, matching diaspora capital with portfolio company investment opportunities. - **Government incentive tracker** β€” Tracks available government grants, incentives, and free zone benefits applicable to portfolio company operations. - **Capital call management** β€” LP capital call scheduling, processing, and reconciliation for fund structure investments. --- ## 5. Compliance and Regulatory Management (`@maat/compliance`) ### 5.1 Ghana Regulatory Infrastructure Maat's compliance module is built Ghana-first because all seven portfolio companies operate primarily under Ghanaian law. The infrastructure encodes the actual regulatory bodies, statutes, and filing obligations so that compliance gaps are surfaced automatically rather than discovered during audits. - **Ghana regulatory body registry** β€” Comprehensive database of all relevant Ghanaian regulatory agencies: Securities and Exchange Commission (SEC), Bank of Ghana (BOG), Food and Drugs Authority (FDA-Ghana), Environmental Protection Agency (EPA), National Communications Authority (NCA), Ghana Revenue Authority (GRA), and sector-specific bodies. - **Ghana regulation catalog** β€” Structured catalog of applicable Ghanaian laws, regulations, and guidelines with version tracking as regulations are amended. - **Regulatory requirement mapping** β€” Maps specific business activities to the applicable regulatory requirements. A company starting a new product line automatically triggers identification of all new applicable regulations. - **License and permit tracker** β€” Tracks all required operating licenses, their current status, renewal dates, conditions, and renewal requirements. - **Regulatory relationship management** β€” Tracks relationships with regulatory officials and manages submission histories for each regulatory body. ### 5.2 Compliance Operations - **Compliance calendar engine** β€” Automated compliance deadline calendar with configurable advance notification periods (30, 14, 7 days before deadline). - **Regulatory change monitoring** β€” Monitors gazette publications, regulatory authority websites, and legal databases for changes affecting portfolio companies. Alerts are linked to the specific business activities affected. - **Compliance gap analysis** β€” Identifies gaps between current business practices and applicable regulatory requirements, prioritized by risk level and remediation effort. - **Audit preparation module** β€” Prepares documentation packages, evidence files, and audit trails for regulatory examinations and external audits. - **Cross-jurisdiction compliance mapper** β€” Maps compliance requirements across multiple African and international jurisdictions for portfolio companies with operations outside Ghana. - **Regulatory filing automation** β€” Auto-generates and tracks regulatory filings and submissions, pre-populating forms from existing company data. - **Compliance training management** β€” Tracks employee compliance training completion, certification status, and expiry dates. ### 5.3 Ethics and ESG Compliance - **Anti-corruption compliance framework** β€” FCPA (US Foreign Corrupt Practices Act), UK Bribery Act, and African Union Convention Against Corruption compliance management. Particularly important for infrastructure and government contracting businesses. - **ESG reporting engine** β€” Environmental, Social, and Governance metric tracking and disclosure preparation aligned to GRI Standards, SASB frameworks, TCFD recommendations, and ISSB standards. - **Environmental impact assessment** β€” Environmental screening and impact assessment for new projects and operational changes. - **Governance compliance tracker** β€” Corporate governance best practice tracking and board reporting for each portfolio company. - **Supply chain ethics monitoring** β€” Ethical sourcing monitoring, child labor detection, and forced labor prevention in supply chains. Aligned to the ILO Fundamental Conventions. - **Ghana data protection compliance** β€” Ghana Data Protection Act (2012) compliance management and privacy impact assessments for data-intensive business activities. - **Intellectual property portfolio manager** β€” Patent, trademark, and copyright portfolio management for portfolio company IP assets. Integrated with Themis for IP governance. --- ## 6. Organization Digital Twin (`@maat/digital-twin`) A digital twin is a real-time computational model of a physical system β€” in this case, each portfolio company's organizational, financial, and operational state. Rather than getting a snapshot when reports are compiled, executives can interrogate the live state of each company at any time and simulate the impact of decisions before committing to them. ### 6.1 State Modeling - **Organization state model** β€” Live data model integrating each company's operational data, financial position, workforce state, supply chain status, and market conditions into a unified computational representation. - **State ingestion pipeline** β€” Continuous ingestion of data feeds from company systems: ERP, HRMS, supply chain platforms, financial systems, and IoT sensors for manufacturing and cold chain businesses. - **Snapshot versioning** β€” Immutable point-in-time state snapshots for audit trails, regulatory reporting, and historical comparison. - **Diff engine** β€” Computes precise state changes between any two snapshots, enabling granular analysis of what changed between any two points in time. - **Data quality monitoring** β€” Monitors the completeness, consistency, and freshness of all incoming state data. Alerts when data sources go stale or show anomalies. ### 6.2 Analysis Capabilities - **Cascade analysis** β€” Traces how a change in one part of the organization propagates through dependent functions. A raw material price increase cascades through COGS, margins, working capital, and cash flow. - **Business unit dependency graph** β€” Maps dependencies and resource flows between departments, business units, and portfolio companies. - **What-if analysis engine** β€” Explores the impact of hypothetical changes before committing: "What happens to margins if we hire 50 engineers?" "How does a 15% GHS depreciation affect our USD debt service?" - **Bottleneck identification** β€” Algorithmically surfaces operational bottlenecks limiting performance. Identifies the constraint in a production process or service delivery chain. - **Impact attribution** β€” Attributes performance outcomes to causal drivers, distinguishing the impact of management decisions from external market movements. ### 6.3 Simulation - **Temporal simulation** β€” Simulates how the organization evolves over time under different assumptions, producing projected state at any future date. - **Facility simulation** β€” Models the utilization and capacity of physical facilities: factories, cold storage, warehouses, construction sites. - **Workforce simulation** β€” Forecasts workforce needs, attrition impact, and the effects of proposed hiring plans on organizational capability. - **Financial cascade simulator** β€” Models how revenue changes cascade through the P&L, balance sheet, and cash flow statement. - **Market shock simulator** β€” Tests organizational resilience to sudden demand shocks, supply disruptions, or pricing crises. - **Multi-objective optimization** β€” Optimizes across competing goals simultaneously: maximize revenue while minimizing cost while improving quality while reducing environmental impact. - **Resource reallocation optimizer** β€” Computes optimal reallocation of people, capital, and assets across different scenarios. - **Scenario manager** β€” Creates, saves, versions, and shares simulation scenarios for collaborative scenario planning. - **Simulation API** β€” Programmatic access to the simulation engine for custom tooling and integration. --- ## 7. Market and Competitive Intelligence (`@maat/intelligence`) ### 7.1 Data Collection and Monitoring - **Market monitor** β€” Real-time monitoring of market prices, indices, and economic indicators relevant to portfolio company industries. - **News aggregator** β€” Aggregates and classifies news relevant to portfolio industries, competitors, and key customers and suppliers. - **Web scraping framework** β€” Configurable scraping infrastructure for collecting competitor pricing, product information, and market data. - **Streaming ingestion** β€” Real-time data streaming from market data providers, commodity exchanges, and news feeds. - **Satellite imagery analysis** β€” Analyzes satellite imagery for supply chain monitoring (tracking vehicles at competitor facilities, estimating crop yields from vegetation indices), facility expansion tracking, and agricultural performance monitoring. ### 7.2 Competitive Analysis - **Competitor tracker** β€” Tracks competitor pricing changes, product launches, leadership changes, regulatory filings, and public statements. - **Competitive positioning engine** β€” Dynamic competitive positioning maps updated from live intelligence, showing how each portfolio company's competitive position shifts over time. - **Patent monitoring service** β€” Watches competitor patent activity for technology trend signals and potential IP conflict risks. - **Supplier intelligence** β€” Monitors supplier financial health, capacity constraints, and reliability signals to anticipate supply chain disruptions. - **Partnership and M&A radar** β€” Identifies potential partnership and acquisition targets matching configured strategic criteria. - **Automated competitive intelligence** β€” Scheduled fully automated competitive research briefings, reducing manual research effort for recurring monitoring tasks. ### 7.3 Intelligence Synthesis Raw signals become executive-level intelligence through the synthesis layer, which combines, scores, and summarizes information from multiple sources into structured briefs that support decisions rather than just reporting facts. - **Sentiment analyzer** β€” NLP-based sentiment analysis of news, social media, and industry reports for brand perception and market sentiment monitoring. - **Trend detector** β€” Identifies emerging trends in markets, consumer behavior, and technology that are relevant to portfolio company strategy. - **Anomaly detection** β€” Flags unusual patterns in market data that may signal significant events: competitor behavior changes, demand shifts, or supplier distress. - **Early warning system** β€” Proactive alerts for emerging threats to portfolio company performance, configurable by risk category and severity threshold. - **Causal inference engine** β€” Distinguishes correlation from causation in business performance data. Did revenue increase because of the new marketing campaign or because of the seasonal cycle? - **Intelligence synthesizer** β€” Combines and summarizes intelligence from multiple sources into executive-level briefings with structured insight and supporting evidence. - **Confidence scoring** β€” Quantifies the reliability and uncertainty of intelligence outputs, enabling executives to calibrate their decision-making to evidence quality. - **NL2SQL interface** β€” Natural language queries against structured portfolio data: "Show me all companies with EBITDA margin below 10% and revenue growth above 20%." - **Voice command interface** β€” Voice-driven access to intelligence reports and dashboards for mobile and hands-free use. - **Multimodal intelligence fusion** β€” Combines text, image, audio, and structured data into unified intelligence products. --- ## 8. Knowledge Management (`@maat/knowledge`) ### 8.1 Document Management - **Document ingestion pipeline** β€” Ingests PDFs, Word documents, spreadsheets, and other formats from portfolio company operations, research, and the external environment. - **Document classification** β€” Automatically classifies documents by type (contract, report, financial filing, regulatory document), domain, and relevance to specific portfolio companies. - **Document summarization** β€” Generates concise AI summaries of lengthy documents, enabling rapid review of large document sets. - **Entity extraction** β€” Extracts named entities (companies, people, products, regulations, financial figures) from documents for knowledge graph population. - **Document versioning and deduplication** β€” Version control for documents with automatic duplicate detection and merging. ### 8.2 Knowledge Graph The knowledge graph is the connective tissue of Maat's intelligence layer β€” it stores not just facts but the relationships between them, enabling multi-hop queries that flat databases cannot support. Today the graph lives in memory; node records are modelled with a `neo4jLabel` field so the schema is ready for projection onto a Neo4j instance when one is wired in. - **Knowledge graph** β€” Graph-structured knowledge base connecting entities, concepts, and relationships in a form that supports complex multi-hop queries. Implemented as an in-memory graph whose node and relationship records carry a `neo4jLabel`, modelled for projection onto a Neo4j datastore (no Neo4j driver is wired today). - **Knowledge graph population** β€” Automated pipeline populating the graph from ingested documents, web scraping, and structured data feeds. - **Knowledge graph enrichment** β€” Continuously enriches existing graph nodes with new information as it is discovered. - **Knowledge graph query interface** β€” Natural language and Cypher-based querying of the knowledge graph. - **Knowledge graph maintenance** β€” Automated stale data detection and graph health monitoring. ### 8.3 Research and Intelligence - **Semantic search** β€” Vector search for conceptually relevant documents beyond keyword matching, finding documents that address the same concepts even when they use different terminology. - **Research corpus manager** β€” Curates and manages collections of research papers, industry reports, and market analyses relevant to each portfolio industry. - **Competitor intelligence system** β€” Structured competitive dossiers for each tracked competitor, built from multiple intelligence sources. - **Industry report library** β€” Repository of industry research reports with structured metadata and automated relevance tagging. - **Knowledge freshness engine** β€” Monitors and flags knowledge that may have become outdated, prompting refresh from current sources. - **Conflict resolution** β€” Detects and resolves conflicting facts in the knowledge base, flagging contradictions for human review. - **Patent landscape engine** β€” Maps patent filing activity to identify technology trends, competitive R&D directions, and IP risks. - **Academic research monitor** β€” Tracks relevant academic publications and research findings in areas relevant to portfolio company industries. - **Knowledge access analytics** β€” Tracks how the knowledge base is being used and what gaps exist (questions asked that returned no results). - **Graph RAG engine** β€” Retrieval-augmented generation using the knowledge graph for grounded AI responses that cite specific knowledge base sources. --- ## 9. Risk Management (`@maat/risk`) ### 9.1 Risk Framework - **Risk taxonomy** β€” Structured classification of risks by type (strategic, operational, financial, compliance, reputational), category, and domain. - **Probability-impact framework** β€” Standardized risk assessment using probability and impact scoring, producing risk registers for each portfolio company. - **Portfolio Monte Carlo simulation** β€” Aggregate risk simulation across the full portfolio, modeling how individual company risks combine at the portfolio level. - **Value at Risk (VaR)** β€” Statistical VaR measurement for financial risk positions (currency, commodity, interest rate exposures) at 95% and 99% confidence levels. ### 9.2 Specific Risk Categories - **Supply chain risk assessment** β€” Quantifies supply chain concentration risk (single-source dependencies), disruption risk (supplier financial fragility), and quality risk. - **Key Risk Indicators (KRIs)** β€” Define and monitor leading indicators that predict future risk materialization, enabling earlier intervention than lagging outcome measures. - **Political risk monitoring** β€” Tracks political stability, policy change likelihood, and regulatory risk in all operating jurisdictions. Critical for West African businesses facing dynamic political environments. - **Currency risk hedging** β€” FX exposure measurement and hedging strategy recommendations for USD/GHS and other currency pairs. - **Commodity price risk** β€” Monitors and models exposure to commodity price volatility for manufacturing and agricultural businesses. - **Cybersecurity risk** β€” IT infrastructure risk assessment and cyber threat monitoring. - **Climate risk** β€” Physical climate risk (flooding, drought, extreme heat) and transition risk (carbon pricing, regulatory change) assessment for all operations. - **Business continuity planning** β€” BCP framework with scenario testing and recovery time objective modeling. - **Insurance portfolio management** β€” Tracks insurance coverage, premium costs, claims history, and coverage gaps. - **Emerging risk radar** β€” Identifies new and evolving risk categories not yet in the formal risk framework. - **Risk appetite management** β€” Defines and communicates risk tolerance thresholds for each portfolio company. --- ## 10. Supply Chain and Trade Intelligence (`@maat/supply-chain`) ### 10.1 Supplier Management - **Supplier map** β€” Visual mapping of the full supplier network with geographic overlays and risk indicator overlays. - **Supplier risk scoring** β€” Quantitative risk scores for each supplier based on financial health indicators, quality history, and delivery reliability. - **Supply chain disruption simulator** β€” Models the cascade impact of supplier failures, logistics disruptions, and demand shocks on the affected portfolio companies. - **Supplier qualification and onboarding** β€” Structured supplier onboarding with compliance checks, ESG screening, and performance benchmarks. - **Supplier diversity and local content** β€” Tracks local supplier and minority supplier spend against diversity targets. ### 10.2 Operations Optimization - **Inventory optimization** β€” Safety stock, reorder point, and order quantity optimization per SKU and location using statistical demand models. - **Logistics routing optimizer** β€” Least-cost and least-time routing across West African multi-modal transport networks. - **Landed cost calculator** β€” Full landed cost calculation including FOB price, freight, marine insurance, customs duties, port charges, inland freight, and handling. - **Warehouse management intelligence** β€” Warehouse layout optimization, slot optimization, and labor productivity analytics. - **Fleet management optimizer** β€” Vehicle routing optimization, preventive maintenance scheduling, and fuel consumption optimization for company vehicle fleets. - **Procurement aggregation** β€” Consolidates purchasing across all portfolio companies to leverage collective volumes for better supplier terms. - **Make vs. buy analysis** β€” Structured framework for outsourcing vs. in-house production decisions incorporating cost, quality, strategic control, and flexibility factors. - **Demand forecasting** β€” Statistical and ML-based demand forecasting across products, markets, and time horizons. - **Raw material price forecasting** β€” Predictive models for key raw material price movements. - **Demand-supply matching** β€” Real-time matching of available supply against forecast demand to prevent stockouts and reduce excess inventory. ### 10.3 African Trade Intelligence West Africa's trade environment β€” ECOWAS tariff harmonization, AfCFTA's progressive duty reduction, and Ghana's free zones β€” creates significant optimization opportunities for businesses that understand the rules. The trade intelligence sub-module encodes those rules as computable logic. - **ECOWAS CET database** β€” Complete West African Economic Community Common External Tariff database for import duty calculations for all ECOWAS member states. - **AfCFTA tariff optimization** β€” Optimizes trade flows to take advantage of African Continental Free Trade Area tariff preferences, which progressively reduce duties between African states. - **Customs documentation generator** β€” Auto-generates customs declarations, certificates of origin (including Form A and AfCFTA preferential certificates), and other trade documents. - **Free trade zone optimization** β€” Identifies opportunities to route trade through Ghanaian and regional free trade zones to minimize tax and duty burden. - **Trade finance intelligence** β€” Letters of credit, documentary collection, and trade finance product optimization for managing payment risk in cross-border transactions. --- ## 11. Workforce Intelligence (`@maat/workforce`) ### 11.1 Organizational Design - **Org design modeler** β€” Models alternative organizational structures and reporting hierarchies, simulating the operational and cost implications of different designs. - **Headcount planning** β€” Forward-looking headcount planning by department, role, grade, and location aligned to business plan assumptions. - **Organizational network analysis** β€” Maps informal influence networks and information flows within organizations, identifying knowledge brokers and coordination bottlenecks not visible in the formal hierarchy. ### 11.2 Talent Intelligence - **Skills gap analysis** β€” Maps current workforce skills against future capability requirements identified from strategic plans and technology roadmaps. - **Compensation benchmarking** β€” Benchmarks compensation levels against local Ghanaian and comparable African market data by role, level, and sector. - **Succession planning** β€” Identifies and develops successors for key leadership and critical technical roles, tracking readiness and development progress. - **Attrition prediction** β€” ML-based prediction of employee attrition risk by individual and team, enabling targeted retention interventions. - **Labor market intelligence** β€” Tracks local talent availability, wage trends, and competitor hiring activity to inform talent strategy. ### 11.3 Workforce Planning - **Payroll modeling** β€” Scenario modeling of payroll cost under different headcount and compensation plan assumptions. - **Diversity tracking** β€” Tracks workforce diversity metrics and progress toward representation goals. - **Contractor optimization** β€” Optimizes the mix of permanent staff and contractors for cost, flexibility, and capability. - **Expatriate management** β€” Manages expatriate assignments, compensation packages, compliance requirements, and relocation support. - **Training ROI** β€” Measures the return on investment of training and development programs using pre/post performance data. - **Workforce scenario planner** β€” Models workforce outcomes under different business, economic, and demographic scenarios. - **Leadership development tracking** β€” Tracks leadership pipeline health and individual development program progress. --- ## 12. Project Portfolio Management (`@maat/projects`) ### 12.1 Project Management - **Project creation engine** β€” Standardized project initiation with templates, stakeholder identification, approval workflows, and baseline setting. - **Gantt chart engine** β€” Interactive Gantt charts with full dependency tracking and critical path calculation identifying the sequence of tasks that determines the minimum project duration. - **Cross-company dependency tracker** β€” Tracks project dependencies that span multiple portfolio companies, preventing uncoordinated scheduling conflicts. - **Resource allocation optimizer** β€” Optimizes allocation of shared resources (management bandwidth, shared services, capital) across competing project demands. - **Earned Value Management (EVM)** β€” Tracks project cost and schedule performance using EVM methodology: Schedule Performance Index, Cost Performance Index, Estimate at Completion, and Variance at Completion. - **Project health scoring** β€” Composite health score combining schedule performance, cost performance, scope stability, stakeholder satisfaction, and risk indicators. - **Portfolio genetic optimizer** β€” Genetic algorithm-based portfolio project selection optimizing the combination of projects for maximum strategic value given resource constraints. ### 12.2 Project Controls - **Project risk register** β€” Structured risk log with probability, impact, owner, and mitigation tracking for each project. - **RACI matrix generator** β€” Automatically generates Responsible, Accountable, Consulted, and Informed matrices from project task structures. - **Milestone payment tracker** β€” Tracks milestone-linked capital disbursements and payment schedules. - **Change request management** β€” Structured change control process with impact assessment and stakeholder approval workflow. - **Lessons learned database** β€” Searchable repository of project lessons for continuous improvement and knowledge transfer across portfolio companies. - **Portfolio dashboard** β€” Executive dashboard showing portfolio-wide delivery performance: on-time rates, cost performance, health distribution, and capacity utilization. - **Project template library** β€” Reusable project templates for common project types: factory construction, technology system implementation, market entry, product launch. --- ## 13. Reporting and Business Intelligence (`@maat/reporting`) The capabilities below are `@maat/reporting` modules. Dashboard _entity_ types (layouts, widgets, data-source bindings, access permissions) are defined in `@maat/core`. The separate `@maat/dashboard` library is currently a scaffold that exports only the V2 balance-dashboard contract (see section 16); the end-user dashboards live in the `apps/maat` web apps. ### 13.1 Automated Reporting - **Board report template** β€” Standardized board pack template with financial performance, operational metrics, strategic priorities, risk update, and outlook sections. - **Investor deck generator** β€” AI-assisted investor presentation generation from portfolio data, producing drafts that analysts can refine. - **KPI scorecard engine** β€” Defines, tracks, and visualizes KPIs at company, business unit, and portfolio levels with traffic light indicators. - **Executive summary AI** β€” Generates concise narrative executive summaries from underlying data, explaining what the numbers mean in plain language. - **MD&A commentary generator** β€” Drafts Management Discussion and Analysis narrative from financial data for regulatory filings and investor communications. - **ESG report generator** β€” Generates ESG disclosures aligned to GRI, SASB, and TCFD frameworks from portfolio company operational and financial data. ### 13.2 Analytics and Visualization - **Chart data generator** β€” Produces chart-ready data structures for all standard visualization types: waterfall, bridge, tornado, scatter, bubble. - **PDF export engine** β€” Exports any report or dashboard view to PDF for distribution. - **Report distribution** β€” Automated scheduling and delivery of reports to configured recipient lists via email or in-platform notification. - **Natural language query interface** β€” Ask questions about portfolio data in plain English and receive structured data and visualizations. - **Cross-company benchmarking** β€” Benchmarks portfolio companies against each other and against external peer groups. - **Cash flow waterfall** β€” Visualizes cash flow distribution through entity structures. - **Ad-hoc report builder** β€” Drag-and-drop report builder for custom analyses not covered by standard templates. --- ## 14. Cross-Company Integration (`@maat/integrations`) `@maat/integrations` provides one connector per portfolio company. Each connector defines the data shapes β€” telemetry, transaction records, analytics feeds β€” that flow from a portfolio company's operational systems into Maat's intelligence and digital-twin layers. The connectors are entirely self-contained inside `@maat/integrations` and do not import the portfolio companies' own Oshun domain libraries. This boundary means Maat is a consumer of operational data, not a dependent of operational logic. The seven portfolio companies, their domains, and the data they supply are: | Company | Domain | Integration Data | | -------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- | | Asase | Agriculture and Cold Chain | Crop yield telemetry, cold chain temperature data, commodity pricing, harvest scheduling | | Freya | Luxury Fashion and E-commerce | Sales transaction data, inventory levels, customer analytics, supply chain | | Cybele | Construction and Property | Project progress data, construction cost tracking, property valuations, contractor performance | | Brigid | Industrial Manufacturing | Production metrics, quality control data, equipment status and maintenance, materials consumption | | Saraswati | R&D, IP, and EV Fleet | Research pipeline status, patent activity, EV fleet telemetry, technology readiness levels | | Iris (Maat portfolio company β€” AI Conversation; distinct from the `@iris/*` Oshun platform domain) | AI Conversation and Agent Orchestration | Conversation analytics, agent performance metrics, platform usage data | | Aje | Blockchain and Digital Assets | Token activity, DeFi position data, transaction flows, smart contract performance | --- ## 15. Developer SDK (`@maat/sdk`) Tools for building custom integrations, extensions, and automation scripts. - **TypeScript client** β€” Fully typed API client for programmatic access to all platform capabilities from Node.js and TypeScript environments. - **CLI tool** β€” Command-line interface for scripting, automation, and data pipeline integration. - **React components** β€” Pre-built UI components for embedding platform views in custom dashboard applications. - **Webhook manager** β€” Configures and manages webhooks for event-driven integrations with external systems. - **API key manager** β€” Manages API keys, permission scopes, and rate limits for developer and integration access. - **Batch operations** β€” Bulk data import, export, and processing via batch APIs for large data operations. - **SSE streaming** β€” Server-sent events for real-time data streaming to client applications. - **Plugin architecture** β€” Extensible plugin system for adding custom data sources, analysis modules, and visualization types. - **Offline mode** β€” Local caching and offline operation support for intermittent connectivity environments common in West African business contexts. - **SDK documentation generator** β€” Auto-generates API reference documentation from SDK type definitions. --- ## 16. Planned Features The following capabilities are planned for upcoming Maat development. ERP streaming, expanded market intelligence, the voice interface, the Themis IP integration, the Aje audit-trail anchor, and the Concordia procurement agents all remain unimplemented. - **Themis IP governance integration** `(planned)` β€” Integration with Themis's IP portfolio management module for centralized trademark, patent, and copyright lifecycle management across all portfolio companies. Themis owns governance primitives; Maat owns business authority. The integration will surface IP events as Maat compliance alerts. - **Product analytics substrate (Phase 142)** `(planned)` β€” Maat's business intelligence consumes the Neith `@neith/metron-*` product-analytics platform (funnels, retention, experiments, attribution) for portfolio-company product metrics, rather than building a parallel event-analytics pipeline; Maat owns the business interpretation layer on top. - **Real-time ERP data streaming** `(planned)` β€” Live streaming integrations with SAP, Odoo, and Microsoft Dynamics ERP systems deployed at portfolio companies, replacing the current batch-ingestion approach with sub-minute state updates in the digital twin. - **Expanded African market intelligence** `(planned)` β€” Extension of market intelligence coverage beyond Ghana to include Nigeria, CΓ΄te d'Ivoire, Senegal, and Kenya, enabling cross-border competitive analysis as portfolio companies expand across West Africa. - **Voice-first executive interface** `(planned)` β€” Conversational voice interface for querying portfolio dashboards and receiving briefings, optimized for executive use during travel and meetings where hands-free interaction is required. - **Blockchain audit trail integration** `(planned)` β€” On-chain anchoring of critical financial and governance decisions via Aje's blockchain infrastructure, providing tamper-evident audit trails for investors and regulators. Aje owns blockchain rails; Maat owns the governance decisions that get anchored. - **Concordia procurement mediation agents** `(partially implemented, Phase 179)` β€” Negotiation intelligence for supplier pricing, payment terms, rebates, volume commitments, service levels, warranty terms, executive approval thresholds, sanctions/KYC checks, segregation of duties, and realized-value measurement. Maat owns business authority and procurement controls; Concordia owns the shared bargaining substrate. The `@maat/negotiation-intelligence` library currently provides the procurement-program configuration scaffold (`ProcurementProgram`/`ProcurementTrack`/`ProcurementLever`/`ApprovalThreshold` schemas and a `toMaatExtensionDefaults` projection into Concordia); the agent mediation behaviour itself is still planned. ### V2 Fighting-Game Cross-Domain Contracts (Implemented) Maat additionally owns three contracts that serve the separate V2 program. These are not portfolio-management features but are implemented in the Maat libraries: the finance persistence ledger (`@maat/finance/v2-persistence-ledger`), the live-ops calendar (`@maat/strategy/v2-fighting-game-live-ops-calendar`), and the balance dashboard (`@maat/dashboard/v2-balance-dashboard`). See `specifications.md` section 7 for details.