WRA Executive Intelligence Platform

WRA Executive Intelligence Platform is the branded product experience for Executive Intelligence Engine, a governed AI platform for turning operational retail data into executive intelligence: scorecards, coaching, recommendations, management workflows, and report-ready insights.

Subtitle: Deterministic Analytics + Explainable AI for Retail Leadership

Supporting brand: Wolfe Retail Advisors

The retail implementation will be the first demonstration of the platform, but the product is intentionally designed as an industry-agnostic engine. The core architecture separates deterministic calculations from AI interpretation so that future implementations can support multiple industries, connectors, prompts, reports, and governance policies without becoming a one-off application.

OpenAI Build Week RC1

This repository is the Release Candidate 1 demonstration for the OpenAI Build Week Work & Productivity track. It shows how a retail advisor can load a reporting month, calculate trusted business facts, and generate a governed Executive Brief with GPT-5.6.

The demonstration company is Carolina Comfort Furniture. It is intentionally a single-company proof of concept using fictional retail data; no customer data or production credentials are included.

Why This Exists

Most AI business tools collapse three very different responsibilities into one layer: ingesting data, calculating business facts, and generating interpretation. That makes systems difficult to audit, difficult to govern, and risky to scale.

WRA Executive Intelligence Platform exists to provide a cleaner model:

• Deterministic business calculations are performed in code.
• AI prompts are versioned, hashed, auditable, and governed.
• AI outputs are treated as interpretations, not sources of truth.
• Reports and workflows are generated from traceable inputs.
• Costs, model usage, and prompt changes are visible to administrators.

The result is a reusable foundation for executive-facing AI systems that can be trusted in operational environments.

Release Candidate

OpenAI Build Week RC1

Application Version: 0.6.0

Status: feature complete for the Build Week demonstration, pending final presentation and release publication.

The candidate includes governed GPT-5.6 analysis, deterministic retail KPIs, a single-company monthly data workflow, audit history, persisted execution evidence, cost visibility, and shared-hosting operational guidance.

HostGator Public Demo Deployment

Prompt 021A adds a HostGator-compatible deployment path for the public demo. Use .env.hostgator.example as the production-safe template, map the web document root to public/, keep storage/ private, run migrations, create the first administrator, and execute:

php scripts/hostgator-smoke-test.php

Detailed instructions are in HostGator Deployment, Backup and Restore, and HostGator Manual Acceptance Checklist.

Executive Retail Workflow

The primary proof-of-concept demonstration flow is:

1. Sign in.
2. Select a reporting month for Carolina Comfort Furniture.
3. Load the selected monthly dataset.
4. Open Executive Overview and review deterministic actual-vs-goal KPIs.
5. Generate an Executive Brief with What should leadership focus on today?
6. Ask follow-up questions about stores, associates, goals, traffic, financing, or protection plans.
7. Review the Executive AI Brief.
8. Open Analysis Details and Audit History.
9. Sign out.

The simplified product workflow is: Authenticate, Select Reporting Month, Load Dataset, Review Deterministic Executive Overview, Generate Executive Brief, Review Analysis Details and Audit History, Take Action, and Repeat with a different month.

flowchart LR
    Login[Authenticate]
    ReportingMonth[Select Reporting Month]
    Import[Load Monthly Dataset]
    Overview[Review Deterministic Executive Overview]
    AI[Generate Executive Brief]
    Reports[Review Reports]
    Audit[Review Audit History]
    Action[Recommend Action]

    Login --> ReportingMonth
    ReportingMonth --> Import
    Import --> Overview
    Overview --> AI
    AI --> Reports
    Reports --> Audit
    Audit --> Action

Loading

When OPENAI_ENABLED=true, OPENAI_API_KEY is configured, and OPENAI_MODEL is one of the approved model IDs, the workflow uses the governed OpenAI service. If OpenAI is unavailable, Ask a Business Question shows a visible warning and does not generate a canned or synthetic executive report. Automated tests may still use the synthetic provider under APP_ENV=testing.

See Prompt 011 Executive Workflow, Prompt 012 Retail Decision Engine, Prompt 013 Governed OpenAI Provider, Prompt 014 MVP Demo Guide, Prompt 015 AI Experience MVP, and Prompt 016 Analysis Details.

Retail CSV Import

The current proof-of-concept import workflow uses six monthly Carolina Comfort Furniture datasets under sample-data/retail-months/. Each month includes a complete reporting period for January through June 2026. The advisor selects a month in Import Data, and the platform activates that month as the current dataset.

Each monthly package includes:

• company_settings.csv: company-wide goals for revenue, conversion, margin, revenue per opportunity, financing, protection plan attachment, and customer satisfaction.
• client.csv: the active company profile, advisor assignment, contact information, systems, retail segment, and company metadata. Existing company.csv files remain accepted as a legacy alias.
• stores.csv: store identity, region, manager, square footage, and opened date.
• users.csv: sales associate identity, initials, role, store assignment, and hire date.
• opportunities.csv: retail traffic and sales opportunities with category, potential amount, financing request, traffic source, and status.
• sales.csv: completed sales linked to opportunities with revenue, margin, protection plan, financing, and delivery type.
• traffic.csv, returns.csv, and labor.csv: supporting deterministic context for the proof-of-concept story.

Downloadable sample files are available inside the application from Import Data. The import validator checks required files, required columns, active company profile, duplicate store IDs, unknown stores, unknown associates, and sale/opportunity relationships before analysis. Goals are embedded in the company, store, and employee files so deterministic reporting can show Goal, Actual, Variance, and Status before AI interpretation.

The dashboard calculates executive KPIs from the loaded dataset, including Executive Health Score, revenue, close rate, average ticket, protection attachment, financing mix, traffic by hour, category mix, store rankings, associate rankings, top store, bottom store, top associate, biggest opportunity, and health-score component points.

Retail Decision Engine

Prompt 012 separates deterministic facts from AI interpretation:

• Curated demonstration data represents four furniture and mattress retail stores across a defined current and comparison period.
• Retail calculations are performed in PHP before provider execution, including conversion rate, average ticket, revenue per opportunity, variance, penetration changes, and benchmark opportunity estimates.
• Opportunity detection uses a small deterministic rule set for conditions such as traffic up with conversion down, low revenue per opportunity, financing decline, protection decline, and high-performing store outliers.
• Prioritization ranks no more than three leadership priorities, two growth opportunities, and one positive practice signal.
• The WRA methodology is Observe, Diagnose, Business Impact, Supporting Evidence, Recommended Action, Expected Outcome, Confidence, and Limitations.
• Audit evidence distinguishes deterministic evidence from AI interpretation and records prompt, model, methodology, calculation, and rule-set versions.

Governed OpenAI Service

Prompt 013 uses the OpenAI Responses API through the existing provider abstraction. The approved model allowlist is gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna, with gpt-5.6-terra as the default configured model. The provider sends store=false by default so WRA retains its own governed execution evidence.

The active governed AI instructions are wra.executive.daily_focus@1.4.1, hashed with SHA-256 and resolved through the prompt registry. The required output schema is wra.executive-brief.schema@1.0.0; returned JSON is validated structurally by OpenAI structured outputs and locally through semantic checks against supplied store IDs, canonical metric keys, rule IDs, and Demo Mode disclosure. The retail context includes a canonical_metric_registry so OpenAI, deterministic calculations, validation, and Analysis Details share the same metric vocabulary.

OpenAI setup is environment-managed. Use OPENAI_API_KEY, OPENAI_ENABLED, OPENAI_API_BASE_URL, OPENAI_MODEL, OPENAI_REASONING_EFFORT, OPENAI_MAX_OUTPUT_TOKENS, OPENAI_STORE_RESPONSES, OPENAI_FALLBACK_ENABLED, OPENAI_PRICING_VERSION, and OPENAI_PRICING_TABLE_JSON. OPENAI_MAX_OUTPUT_TOKENS defaults to 4000, the recommended minimum for governed structured executive responses. OPENAI_FALLBACK_ENABLED defaults to false for live demo trust; user-facing analysis does not silently substitute synthetic output. Never commit .env, API keys, bearer tokens, response dumps, or provider debug output.

AI cost display uses the actual model and token usage returned by the provider. Prompt 018A centralizes governed GPT-5.6 pricing in the OpenAI pricing registry so completed OpenAI executions can display AI Cost without scattering vendor rates through business logic. OPENAI_PRICING_TABLE_JSON remains available for approved pricing updates without changing application code.

Default governed GPT-5.6 rates are stored as per-million-token prices:

Model	Input	Cached Input	Output
gpt-5.6-sol	USD 5.00	USD 0.50	USD 30.00
gpt-5.6-terra	USD 2.50	USD 0.25	USD 15.00
gpt-5.6-luna	USD 1.00	USD 0.10	USD 6.00

Use OPENAI_PRICING_TABLE_JSON only when replacing or augmenting the approved registry:

{
  "gpt-5.6-terra": {
    "input_cost_per_1m_tokens": 2.50,
    "cached_input_cost_per_1m_tokens": 0.25,
    "output_cost_per_1m_tokens": 15.00,
    "currency": "USD",
    "source": "approved_override",
    "source_note": "Approved pricing update reference."
  }
}

The formula is ((input_tokens - cached_input_tokens) / 1000000 * input_price) + (cached_input_tokens / 1000000 * cached_input_price) + (output_tokens / 1000000 * output_price). Cost calculation uses decimal-safe integer micro-dollar arithmetic and stores pricing version, pricing table source, raw usage, OpenAI request ID when available, calculated timestamp, currency, token counts, and input, cached input, output, and total costs. If pricing or usage cannot be validated, the product displays AI Cost Unavailable instead of $0.00.

Technology Stack

• PHP 8.3+
• Composer
• MySQL
• Bootstrap 5
• Vanilla JavaScript
• HTML5
• CSS
• PSR-4 autoloading
• Object-oriented, MVC-inspired architecture
• No application framework

Quick Start

Windows PowerShell:

.\scripts\bootstrap-dev.ps1
php -S 127.0.0.1:8080 -t public public/router.php

macOS/Linux:

chmod +x scripts/bootstrap-dev.sh
./scripts/bootstrap-dev.sh
php -S 127.0.0.1:8080 -t public public/router.php

Open:

• http://127.0.0.1:8080/
• http://127.0.0.1:8080/health
• http://127.0.0.1:8080/ready
• http://127.0.0.1:8080/login

The local server uses public/router.php so existing static assets such as /css/app.css, /js/app.js, and images are served directly by PHP's built-in server. Only non-existent paths are routed through public/index.php.

Windows Setup

1. Install PHP 8.3 or later and confirm it is available:

php -v

2. Install Composer from the official Composer installer and confirm it is available:

composer --version

3. Install dependencies:

composer install

4. Create local environment configuration without overwriting secrets:

Copy-Item .env.example .env

5. Create writable storage directories:

New-Item -ItemType Directory -Force -Path storage/logs, storage/reports, storage/prompts, storage/uploads, storage/cache, storage/tmp

6. Run verification:

composer syntax
composer smoke
composer test

7. Start the local server using public/ as the document root:

php -S 127.0.0.1:8080 -t public public/router.php

The automated setup path is:

.\scripts\bootstrap-dev.ps1

macOS/Linux Setup

1. Install PHP 8.3 or later and Composer using your system package manager or the official Composer installer.
2. Confirm local tooling:

php -v
composer --version

3. Bootstrap the project:

chmod +x scripts/bootstrap-dev.sh
./scripts/bootstrap-dev.sh

4. Start the local server:

php -S 127.0.0.1:8080 -t public public/router.php

Local Test Commands

Composer scripts:

composer syntax
composer smoke
composer test
composer verify
composer serve
composer db:migrate-status
composer db:migrate
composer db:seed

Direct smoke test:

php scripts/smoke-test.php

composer verify runs syntax checks, the smoke test, and PHPUnit.

Engineering Workflow

The repository includes a standard engineering operating system for future prompts, reviews, and releases:

• AGENTS.md defines required Codex and contributor instructions.
• Engineering Playbook defines the planning, implementation, tollgate, remediation, acceptance, and release lifecycle.
• Tollgate Checklist defines Engineering Tollgate, Architecture Review, and Evidence Acceptance expectations.
• Release Checklist defines release preparation, validation, tagging, publication, and post-release checks.

Release candidates should run the reusable verifier:

powershell -ExecutionPolicy Bypass -File scripts/verify-release.ps1

The verifier writes local evidence to docs/releases/evidence/release-local-evidence.md. That file is generated-only, intentionally ignored by Git, and may be regenerated at any time. Its recorded Git commit SHA must match the HEAD under review, so rerun release verification after every release-affecting commit. The evidence output is redacted and must never contain API keys, cookies, authorization headers, CSRF values, session identifiers, database credentials, or other secrets.

Release verification also runs focused CSRF and authenticated Ask a Business Question workflow checks. These verify that a signed-in administrator can reach the analysis interface and, under APP_ENV=testing, submit the verified analysis form through the deterministic test provider path without making a live OpenAI call. Local demo verification with APP_ENV=local requires configured OpenAI for user-facing analysis.

Prompt-specific verification scripts may be passed as a feature verifier:

powershell -ExecutionPolicy Bypass -File scripts/verify-release.ps1 -FeatureVerifier scripts/verify-prompt-005a.ps1

Expected Runtime Responses

GET /health returns safe JSON similar to:

{
  "status": "ok",
  "application": "WRA Executive Intelligence Platform",
  "version": "0.6.0",
  "timestamp": "2026-07-16T00:00:00+00:00"
}

GET /ready returns safe JSON similar to:

{
  "status": "ready",
  "application": "WRA Executive Intelligence Platform",
  "version": "0.6.0",
  "checks": [
    {
      "name": "core",
      "status": "ok",
      "message": "Core services loaded."
    },
    {
      "name": "database",
      "status": "failed",
      "message": "Database connection is unavailable."
    },
    {
      "name": "governance",
      "status": "ok",
      "message": "Governance services loaded."
    },
    {
      "name": "prompt_registry",
      "status": "ok",
      "message": "Prompt registry service loaded."
    },
    {
      "name": "migrations",
      "status": "ok",
      "message": "19 migration files discovered."
    },
    {
      "name": "authentication",
      "status": "ok",
      "message": "Authentication services loaded."
    },
    {
      "name": "authorization",
      "status": "ok",
      "message": "Authorization roles and permissions loaded."
    },
    {
      "name": "organizations",
      "status": "ok",
      "message": "Organization services loaded."
    },
    {
      "name": "sessions",
      "status": "ok",
      "message": "Session and CSRF services loaded."
    }
  ]
}

The database, governance, identity, authorization, organization, and session checks return only readiness state and safe messages. A local database that is not running may cause /ready to return HTTP 503 with status: "not_ready". These endpoints must not expose API keys, database passwords, authorization headers, cookies, full configuration values, connection strings, prompt bodies, or filesystem paths.

Troubleshooting

If composer is not recognized on Windows, install Composer with the official Windows installer, restart PowerShell, and run:

composer --version

If PHP is not recognized, confirm PHP 8.3+ is installed and that the PHP executable directory is on PATH.

If bootstrap or readiness reports a database connection problem, run the safe database diagnostic:

php bin/eie database:diagnose

The diagnostic checks configuration presence, PDO driver availability, connection, and SELECT 1 without printing credentials, usernames, full DSNs, connection strings, raw environment values, tokens, or secrets. See Initial Administrator Bootstrap for diagnostic categories and manual configuration requirements.

If PHPUnit is missing, run:

composer install

If the app starts from the wrong directory, make sure the local server uses public/ as the document root:

php -S 127.0.0.1:8080 -t public public/router.php

The router script must be included in local development. It returns control to PHP's built-in server for existing static files and sends application routes such as /, /login, /health, /ready, and /admin through the front controller.

Architecture Overview

Executive Intelligence Engine is organized around clear platform domains:

• Core: application bootstrap, configuration access, routing, and shared platform contracts.
• AI: model adapters, prompt management, validation, costing, audit, and versioning.
• Connectors: import and integration framework for operational data sources.
• Scoring: deterministic business calculations and scorecard preparation.
• Governance: policies, approvals, audit requirements, and platform controls.
• Reports: report builders, templates, PDF output, and future delivery workflows.
• Admin: administrative workflows for managing connectors, prompts, usage, and governance.
• Auth: authentication and authorization boundaries.
• Controllers, Services, Repositories, Models, Utilities: MVC-inspired application layers.
• Contracts: platform-wide interfaces for configuration, logging, auditing, time, identifiers, HTTP, connectors, AI, prompts, costing, validation, reports, and service providers.

The platform is designed so that deterministic computation, AI interpretation, governance, and presentation remain independently testable.

Architecture Diagrams

Runtime Boundary

flowchart LR
    Browser[Browser or API Client]
    PublicRoot[Public Web Root]
    Kernel[Application Kernel]
    Router[Router]
    Controllers[Controllers and Route Handlers]
    Services[Application Services]
    Container[Dependency Container]
    ConfigRepo[Configuration Repository]
    Scoring[Deterministic Scoring]
    AIService[AI Orchestration]
    Reports[Report Generation]
    Governance[Governance Controls]
    Policy[Execution Policies]
    AuditLog[AI Audit Log]
    CostTracking[Cost Tracking]
    Prompts[Versioned Prompts]
    Models[Model Registry]
    Identity[Identity Services]
    Users[Users]
    Roles[Roles and Permissions]
    Organizations[Organizations]
    Connectors[Data Connectors]
    Repositories[Repositories]
    Database[MySQL]
    ReportStorage[Report Storage]

    Browser --> PublicRoot
    PublicRoot --> Kernel
    Kernel --> Router
    Router --> Controllers
    Controllers --> Services
    Kernel --> Container
    Kernel --> ConfigRepo
    Services --> Scoring
    Services --> AIService
    Services --> Reports
    AIService --> Governance
    Governance --> Policy
    Governance --> AuditLog
    Governance --> CostTracking
    Governance --> Prompts
    Governance --> Models
    Services --> Identity
    Identity --> Users
    Identity --> Roles
    Identity --> Organizations
    Connectors --> Services
    Repositories --> Database
    Services --> Repositories
    Reports --> ReportStorage

Loading

Request Lifecycle

flowchart TD
    Client[Client]
    PublicIndex[Public Index]
    Kernel[Application Kernel]
    Config[Load Config and Providers]
    Router[Router]
    Handler[Route Handler]
    Response[Safe Response]

    Client --> PublicIndex
    PublicIndex --> Kernel
    Kernel --> Config
    Config --> Router
    Router --> Handler
    Handler --> Response
    Response --> Client

Loading

Governed AI Flow

flowchart TD
    OperationalData[Operational Data]
    Connector[Connector Contract]
    NormalizedData[Normalized Platform Data]
    Score[Deterministic Score Calculation]
    Prompt[Prompt Registry and Version]
    PromptHash[Prompt Hash]
    Validation[Input and Output Validation]
    ModelAdapter[Model Adapter]
    AuditEvent[Audit Event]
    CostRecord[Cost Record]
    Interpretation[AI Interpretation]
    Report[Executive Report]

    OperationalData --> Connector
    Connector --> NormalizedData
    NormalizedData --> Score
    Score --> Prompt
    Prompt --> PromptHash
    PromptHash --> Validation
    Validation --> ModelAdapter
    ModelAdapter --> AuditEvent
    ModelAdapter --> CostRecord
    ModelAdapter --> Interpretation
    Interpretation --> Report

Loading

Persistence Flow

flowchart TD
    DbConfig[Typed Database Config]
    DbManager[Database Manager]
    ConnectionPool[Connection Pool]
    DbConnection[PDO Database Connection]
    Repository[Generic Repository]
    QueryBuilder[Query Builder]
    TransactionManager[Transaction Manager]
    MigrationRunner[Migration Runner]
    MigrationRepository[Migration Repository]
    SchemaMigrations[Schema Migrations]
    SeederRunner[Seeder Runner]
    ReadinessCheck[Readiness Check]
    MySQL[MySQL]

    DbConfig --> DbManager
    DbManager --> ConnectionPool
    ConnectionPool --> DbConnection
    Repository --> QueryBuilder
    QueryBuilder --> DbConnection
    TransactionManager --> DbConnection
    MigrationRunner --> MigrationRepository
    MigrationRepository --> SchemaMigrations
    SeederRunner --> DbConnection
    ReadinessCheck --> DbManager
    DbConnection --> MySQL

Loading

Governed Execution Lifecycle

flowchart TD
    Request[Execution Request]
    Validate[Request Validation]
    Prompt[Prompt Resolution]
    Model[Model Resolution]
    Policy[Policy Evaluation]
    Provider[AI Provider Adapter]
    Output[Output Validation]
    Tokens[Token Accounting]
    Cost[Cost Calculation]
    Result[Result Assembly]
    Audit[Audit Logging]
    Store[Execution Store]
    Replay[Replay Metadata]
    Response[Execution Response]

    Request --> Validate
    Validate --> Prompt
    Prompt --> Model
    Model --> Policy
    Policy --> Provider
    Provider --> Output
    Output --> Tokens
    Tokens --> Cost
    Cost --> Result
    Result --> Audit
    Audit --> Store
    Store --> Replay
    Replay --> Response

Loading

Folder Structure

/
+-- config/                 Application configuration placeholders
+-- database/               Migrations and seed data
+-- docs/                   Architecture, operations, planning, release, security, and governance documentation
+-- prompts/                Governed prompt source artifacts
+-- public/                 Web entry point and public assets
+-- sample-data/            Non-sensitive demonstration data
+-- src/                    PSR-4 application source code
+-- storage/                Runtime-generated files, logs, reports, cache, and uploads
+-- tests/                  Automated test placeholders

Application Boot Sequence

1. public/index.php loads Composer autoloading when available, with a local development fallback autoloader.
2. .env values are loaded without overriding existing process environment variables.
3. App\Core\Application is created with the repository root path.
4. The kernel loads typed configuration, registers base services, registers service providers, and registers routes.
5. The kernel builds an App\Http\Request, dispatches it through App\Http\Router, applies safe headers, and sends an App\Http\Response.
6. Catastrophic bootstrap failures return a generic 500 response without leaking secrets.

Dependency Container

The runtime includes a lightweight container implementing App\Contracts\ContainerInterface.

• Binds interfaces to implementations.
• Supports singletons, factories, and object instances.
• Resolves constructor dependencies where types are explicit.
• Detects circular dependencies.
• Prevents silent service replacement unless replacement is explicitly requested.

Service Providers

Service providers implement App\Contracts\ServiceProviderInterface and are listed in config/providers.php.

Initial providers:

• CoreServiceProvider
• LoggingServiceProvider
• DatabaseServiceProvider
• GovernanceServiceProvider
• HttpServiceProvider

Providers register services into the container and may boot after the application kernel is available. Arbitrary plugin directory loading is intentionally not implemented yet.

HTTP Runtime

The platform owns its HTTP abstractions:

• App\Http\Request
• App\Http\Response
• App\Http\JsonResponse
• App\Http\HtmlResponse
• App\Http\RedirectResponse
• App\Http\Router

Initial routes:

• GET /
• GET /health
• GET /ready

The router supports GET and POST routes, named routes, route parameters, route prefixes, 404 handling, and 405 handling. Middleware-ready route structure is present, but a full middleware pipeline is deferred.

Health And Readiness

GET /health confirms that the application process is running and returns safe JSON with application name, version, status, and UTC timestamp.

GET /ready confirms that configuration, core services, database readiness, governance services, prompt registry services, and migration discovery loaded correctly. It does not expose environment secrets, database credentials, connection strings, file-system paths, API keys, prompt bodies, or full configuration values.

Future readiness checks can be registered through:

• HealthCheckInterface
• HealthCheckResult
• HealthCheckRegistry

Persistence Architecture

The persistence layer is framework-free and PDO-backed. It is designed around small components:

• DatabaseConfig: typed database configuration and safe summaries.
• ConnectionFactory: creates PDO-backed database connections.
• ConnectionPool: stores named connections for future multi-database support.
• DatabaseConnection: wraps PDO execution, safe parameter binding, read-only checks, and slow-query logging hooks.
• DatabaseManager: resolves default, read, and write connections.
• TransactionManager: wraps callbacks in commit/rollback behavior and logs failures.
• QueryBuilder: lightweight read-query builder with safe identifier validation and bound parameters.
• MigrationRunner: discovers and applies migration files.
• MigrationRepository: stores schema migration history.
• SeederRunner: discovers and executes seeders.

The target database is MySQL through PDO. Database connectivity is not required during application boot, but /ready includes a database health check.

Required PHP database extensions:

• Production and local application runtime: pdo_mysql and a reachable MySQL database.
• Fast automated persistence tests: pdo_sqlite and sqlite3 for in-memory test databases.

SQLite is test-only in this repository. It is used for fast unit-level persistence and transaction coverage, and it does not replace targeted MySQL integration validation for production database compatibility.

Repository Pattern

Generic repository primitives live under src/Repositories.

• RepositoryInterface
• ReadRepositoryInterface
• WriteRepositoryInterface
• BaseRepository
• Filter, FilterCollection
• Sort
• Pagination
• QueryOptions

The base repository supports generic reads, inserts, updates, deletes, filtering, sorting, pagination, and optimistic locking placeholders through an expected version argument. Business repositories are intentionally not created yet.

Migration Philosophy

Migrations are append-only operational artifacts that advance schema state in a controlled order. Each migration returns a MigrationInterface instance and exposes an immutable migration ID. Applied migrations are tracked in schema_migrations.

Run migration commands with:

php scripts/database.php migrate:status
php scripts/database.php migrate

Composer helpers:

composer db:migrate-status
composer db:migrate

Seeder Philosophy

Seeders are environment-aware setup helpers for non-production data and development workflows. Prompt 003 includes only a placeholder development seeder. No retail, customer, or business data is seeded.

Run seeders with:

php scripts/database.php seed
composer db:seed

Connection Lifecycle

Database connections are created lazily through DatabaseManager and cached in ConnectionPool. The design supports future named read/write connections and multi-database expansion while keeping Prompt 003 focused on one MySQL-backed configuration.

Read-only query support is available through the read connection name. Write statements attempted on read-only connections are rejected before execution.

Transaction Handling

TransactionManager wraps work in a database transaction and guarantees rollback on failure. Transaction failures are logged with safe context and without credentials or connection strings.

Future Scaling Strategy

The persistence layer is prepared for high-volume audit logs, prompt history, model usage, connector runs, governance events, organizations, and future plugins. Future milestones should add indexes, retention policies, partitioning strategies, read replicas, archival workflows, and domain-specific repositories only when their schemas are introduced.

Governance Architecture

Prompt 004 adds a governance domain under src/Governance for future AI execution controls. It is intentionally execution-free: it defines the objects, registries, policies, audit records, replay references, and cost accounting needed before model adapters are introduced.

Core governance components include:

• PromptRegistry, PromptVersion, PromptManifest, PromptLifecycle, and PromptHashService.
• ModelRegistry, ModelDefinition, and ModelVersion.
• ExecutionRequest, ExecutionContext, ExecutionMetadata, ExecutionReference, and ExecutionResult.
• AuditEvent, AuditWriter, AuditReader, AuditSearch, AuditTimeline, AuditRetentionPolicy, and AuditExport.
• TokenUsage, TokenEstimator, CostEstimator, ExecutionCost, UsageSummary, and ProviderCostSchedule.
• ReplayRequest, ReplayEngine, ReplayComparison, and ReplayValidation.
• ExplanationRecord, ReasoningMetadata, ConfidenceMetadata, EvidenceReference, HumanReview, and HumanDecision.
• ExecutionPolicy, ApprovalPolicy, RetentionPolicy, and LoggingPolicy.

Prompt Lifecycle

Prompt definitions move through a governed lifecycle: draft, review, approved, deprecated, and archived. Prompt metadata stores identifier, semantic version, display name, internal name, description, category, owner, effective and retirement dates, token estimate, change notes, approval placeholders, parent version, child version, and a SHA-256 hash.

Approved prompt versions are immutable. Future changes must create a new semantic version with a new hash and lifecycle record.

Prompt Governance

Prompt bodies should be stored as governed artifacts and referenced by stable paths or IDs. Runtime and audit records should store prompt identifiers, semantic versions, hashes, and references rather than dumping raw prompt bodies into logs, readiness responses, or public diagnostics.

Audit Philosophy

The audit engine is audit-first and append-only by design. Every future AI execution should emit governed records with request ID, correlation ID, execution ID, prompt version, prompt hash, model version, execution time, latency, token usage, estimated cost, status, and future user or organization references.

Audit serialization is safe by default and excludes credentials, API keys, authorization headers, cookies, prompt secrets, and full request bodies.

Replay Philosophy

Replay records preserve the references needed to reproduce a prior execution with the same prompt version, prompt hash, model version, and input references. Prompt 004 provides replay DTOs and validation placeholders only. No AI replay or model execution occurs yet.

Model Registry

The model registry is provider-neutral. Model metadata supports provider, model name, release version, capabilities, context window, JSON support, structured output support, reasoning support, status, cost metadata placeholders, and availability. GPT-5.6 prices are centralized in the governed OpenAI pricing registry, and approved updates can be supplied through configuration rather than business workflow code.

Cost Accounting

Token and cost accounting use provider schedules supplied by governed registries, configuration, or future administration workflows. For completed OpenAI executions, the platform calculates actual AI cost from provider token usage and the active pricing schedule, persists the pricing evidence, and surfaces organization, user, model, and time-period reporting for operational review.

Governed Execution Policy

The policy layer establishes reusable checks that execution pipelines must satisfy before reaching any model adapter. Prompt 006 routes execution requests through approved-prompt checks, registered-model checks, provider resolution, validation, audit, persistence, and replay metadata. Policies may approve, reject, or require human review.

Governed AI Execution Runtime

Prompt 006 adds the first executable AI engine under src/AI/Execution. The runtime treats every AI interaction as a governed transaction rather than a raw provider call.

Pipeline stages include:

• Request validation
• Prompt resolution
• Model resolution
• Policy evaluation
• Provider execution
• Output validation
• Token accounting
• Cost calculation
• Result assembly
• Audit logging
• Persistence

Provider-specific behavior is isolated behind adapters under src/AI/Providers. The deterministic synthetic provider supports tests and local validation without external calls. The OpenAI adapter is registered through the provider boundary and requires explicit configuration before real provider use.

Connector Runtime

Prompt 007 adds the governed connector runtime under src/Connectors. The runtime treats external data intake as an auditable platform transaction rather than an ad hoc import.

Connector runtime components include:

• Connector definitions, capabilities, registry, and discovery.
• Organization-scoped connector configuration using credential references instead of credential values.
• Read-only ConnectorExecutionService orchestration.
• Synthetic connector support for tests without external service calls.
• Database-backed connector definitions, configurations, runs, and run events.
• Governed audit event integration for connector execution outcomes.
• Connector readiness checks and safe failure classification.

Prompt 007 intentionally does not implement TrakWell, retail data normalization, write-back behavior, dashboards, reports, or connector credential storage.

Identity Architecture

Prompt 005 adds a framework-free identity layer under src/Auth, src/Authorization, src/Organizations, src/Settings, and src/Admin. The design assumes future enterprise multi-tenancy: every future prompt execution, connector run, report, audit event, and cost record should be attributable to an organization, user, role, and permission set.

Identity components include users, user profiles, user statuses, password hashing, password policy validation, password reset token placeholders, email verification token placeholders, user repository contracts, user services, and validators. User statuses include active, disabled, locked, and pending verification. The user model includes future SSO compatibility metadata without implementing SSO yet.

RBAC

Authorization is role based and permission driven. Prompt 005 defines configurable permissions, permission groups, roles, role assignments, authorization services, and policy evaluation.

Prompt 005 Review wires RBAC into the administration runtime. Every protected administration route requires an explicit server-side permission. Anonymous requests receive HTTP 401. Authenticated users without the required permission receive HTTP 403. Client-side navigation is never treated as an authorization boundary.

Initial roles include:

• System Administrator
• Organization Administrator
• Manager
• Analyst
• Viewer
• Developer

Permissions are expressed as stable keys such as admin.access, users.manage, organizations.manage, roles.manage, permissions.manage, settings.manage, audit.view, prompts.view, models.view, and costs.view.

Session Lifecycle

The authentication framework includes login and logout routes, remember-me capable session metadata, session validation, session rotation, session expiration, secure cookie attributes, CSRF token issuance and validation, brute-force protection, and account lockout placeholders.

Session cookies are configured through environment-backed security settings. Production should use secure cookies, HttpOnly cookies, SameSite policy, short session lifetimes, and explicit remember-me lifetimes. Local development may relax COOKIE_SECURE when using http://127.0.0.1.

All state-changing authentication and administration routes must validate CSRF tokens. Login and logout forms render hidden CSRF tokens and reject missing or invalid tokens. Future password reset, user management, organization management, role management, permission management, and settings update forms must use the same CSRF validation path.

No MFA implementation is included in Prompt 005. The design leaves room for future MFA and SSO providers.

Organization Model

Organizations are first-class tenancy boundaries. Prompt 005 includes organization entities, organization profiles, organization settings, repository contracts, services, and readiness checks.

The model is prepared for future support of multiple organizations, organization ownership, branding, licensing, and custom AI model configuration.

Prompt 005 Review strengthens organization isolation in the identity schema. User, session, role-assignment, token, and organization-setting tables include foreign keys, uniqueness rules, and lookup indexes where migration order supports enforcement.

Administration Architecture

Prompt 005 adds a protected administration shell with routes for:

• /login
• /logout
• /admin
• /admin/users
• /admin/organizations
• /admin/settings
• /admin/system

Administration pages include navigation, version display, current-user placeholder, health indicators, user management, organization management, role and permission management placeholders, application settings, system information, prompt registry access placeholder, audit access placeholder, model registry access placeholder, cost ledger placeholder, and execution history placeholder.

No retail-specific administration pages are included.

Initial administrator creation is a controlled CLI workflow:

php bin/eie bootstrap:admin

The command creates the first organization and administrator, verifies required permissions, creates the deterministic platform_administrator role, assigns the role, writes safe audit events, and rolls back the transaction if any step fails. A singleton database bootstrap marker prevents concurrent first-run commands from creating multiple initial administrators. Do not place administrator passwords in source control, documentation, shell history, or chat transcripts. See Initial Administrator Bootstrap and the Documentation Index.

Identity Security Model

Password hashing uses Argon2id. Password policy requires enterprise complexity. Sessions use opaque identifiers, rotation support, expiration, HttpOnly cookies, SameSite cookies, and CSRF token validation. Authorization checks are permission based and organization scoped.

Argon2id parameters are configurable through ARGON_MEMORY_COST, ARGON_TIME_COST, and ARGON_THREADS. Session and cookie behavior is configurable through SESSION_TIMEOUT, REMEMBER_ME_LIFETIME, COOKIE_SECURE, and COOKIE_SAMESITE. Login throttling is configurable through LOGIN_MAX_ATTEMPTS and LOGIN_LOCKOUT_MINUTES.

The identity layer must never store plaintext passwords and must never log credentials, session tokens, CSRF tokens, cookies, authorization headers, or password reset tokens.

Identity events are recorded through the governed audit engine, not only application logs. Covered events include login success, login failure, logout, session creation, session rotation, session expiration, user creation, organization creation, role assignment, role removal, and administrative access. Audit records store safe references such as event type, actor reference, organization reference, target reference, correlation or request ID, UTC timestamp, status, and safe metadata. They must not store passwords, raw session IDs, reset tokens, verification tokens, CSRF values, cookies, or authorization headers.

Configuration Rules

• .env is supported for local configuration.
• Existing environment variables take precedence over .env.
• .env.example documents required and optional keys.
• Typed access is provided through ConfigInterface.
• Required-value validation is supported.
• Boolean and integer parsing is centralized.
• Secret values are not included in configuration exceptions or readiness responses.

Supported configuration keys include APP_ENV, APP_DEBUG, APP_URL, APP_TIMEZONE, APP_NAME, APP_VERSION, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, LOG_LEVEL, SESSION_TIMEOUT, REMEMBER_ME_LIFETIME, COOKIE_SECURE, COOKIE_SAMESITE, LOGIN_MAX_ATTEMPTS, LOGIN_LOCKOUT_MINUTES, ARGON_MEMORY_COST, ARGON_TIME_COST, and ARGON_THREADS.

AI execution configuration keys include OPENAI_ENABLED, OPENAI_API_KEY, OPENAI_API_BASE_URL, OPENAI_MODEL, OPENAI_REASONING_EFFORT, OPENAI_TIMEOUT_SECONDS, OPENAI_CONNECT_TIMEOUT_SECONDS, OPENAI_MAX_OUTPUT_TOKENS, OPENAI_STORE_RESPONSES, OPENAI_FALLBACK_ENABLED, OPENAI_PRICING_VERSION, OPENAI_PRICING_TABLE_JSON, OPENAI_ORGANIZATION, OPENAI_PROJECT, and budget threshold settings. OPENAI_MAX_OUTPUT_TOKENS should remain at or above 4000 for complete governed structured output. OPENAI_PRICING_VERSION defaults to openai-gpt-5.6-pricing@prompt-018a. OPENAI_PRICING_TABLE_JSON stores optional non-secret model pricing overrides used for accurate cost display. OPENAI_API_KEY is secret and must never be committed, logged, rendered, persisted in execution records, or included in diagnostics. OPENAI_FALLBACK_ENABLED defaults to false; synthetic provider output is reserved for automated testing.

Bootstrap configuration keys include BOOTSTRAP_ENABLED, BOOTSTRAP_ALLOW_NON_INTERACTIVE, BOOTSTRAP_ORGANIZATION_NAME, BOOTSTRAP_ADMIN_NAME, and BOOTSTRAP_ADMIN_EMAIL. BOOTSTRAP_ADMIN_PASSWORD is supported only as a temporary non-interactive environment value and is intentionally omitted from .env.example.

Recommended development values:

COOKIE_SECURE=false
COOKIE_SAMESITE=Lax
SESSION_TIMEOUT=1800
REMEMBER_ME_LIFETIME=2592000

Recommended production values:

COOKIE_SECURE=true
COOKIE_SAMESITE=Lax
SESSION_TIMEOUT=1800
REMEMBER_ME_LIFETIME=2592000

Logging And Redaction

The logging foundation writes structured JSON lines under storage/logs.

Each record includes UTC timestamp, log level, event name, application name, version, environment, and redacted context. The redactor masks sensitive keys such as passwords, API keys, tokens, authorization headers, cookies, and database credentials.

The logger does not record complete request bodies, cookies, authorization headers, environment secrets, API keys, or database passwords.

Database logging hooks record connection failures, slow queries, transaction failures, migration events, seeder events, and schema version events with safe metadata only.

AI execution logs should include correlation ID, execution ID, prompt version, prompt hash, model version, elapsed time, and status. They must not include prompt secrets, API keys, credentials, authorization headers, cookies, or raw prompt/input bodies.

Error Lifecycle

Exceptions are handled centrally by App\Core\ExceptionHandler.

• Production responses hide stack traces and internal exception messages.
• Development mode may include safe debug details.
• Error responses include the request ID.
• API-style requests receive JSON errors.
• Browser requests receive HTML errors.
• Exceptions are logged through the structured logger with redaction.

UTC Time

The platform uses UTC internally through App\Contracts\ClockInterface and App\Support\Clock\SystemClock. APP_TIMEZONE is reserved for display concerns and does not change internal audit, health, logging, or execution timestamps.

Testing Status

PHPUnit configuration and tests are included for configuration parsing, required configuration validation, container binding and resolution, singleton resolution, circular dependency detection, router dispatch, 404 handling, 405 handling, JSON responses, health endpoint structure, readiness endpoint structure, UTC clock behavior, identifier uniqueness, secret redaction, production exception behavior, persistence primitives, prompt hashing, prompt versioning, audit serialization, cost calculations, policy validation, execution DTOs, replay DTOs, registry loading, governance migration validation, password hashing, authentication, authorization, session lifecycle, CSRF validation, organization management, administration routing, settings validation, identity migration validation, admin authorization enforcement, secure cookie behavior, identity audit integration, and secret exposure smoke-test detection.

Developer Workstation Verification

Prompt 005 Review was verified on a developer workstation with PHP 8.3+ and Composer installed.

Recommended commands:

composer install
composer validate
composer diagnose
composer verify
vendor/bin/phpunit

Latest local verification:

• PHP 8.3.31.
• Composer 2.10.2.
• composer validate passed.
• composer diagnose passed.
• composer verify passed.
• Smoke test passed.
• PHPUnit 11.5.56 passed with 56 tests and 193 assertions.
• PHP syntax checks passed for all non-vendor PHP files.

Codex Execution Environment

Composer and PHP were unavailable on the Codex execution PATH, so Composer commands, PHPUnit, smoke tests, and PHP syntax checks were not executed inside the Codex shell.

Static verification completed successfully in the Codex execution environment:

• composer.json valid.
• composer.lock valid.
• phpunit.xml valid.
• Mermaid inspection passed.
• Secret scan passed.
• vendor/ excluded by .gitignore.

Run the full verification suite on a PHP-enabled workstation with:

composer install
composer validate
composer diagnose
composer verify
vendor/bin/phpunit

Coding Standards

• Use strict typing in all PHP files.
• Use namespaced, object-oriented PHP.
• Follow PSR-4 autoloading through Composer.
• Keep business calculations deterministic and testable.
• Keep AI prompts and model interactions isolated from controllers.
• Avoid framework-specific patterns so the platform remains portable.
• Prefer small interfaces and explicit contracts over hidden global behavior.
• Do not commit secrets, production data, generated reports, logs, or cache files.

Security Philosophy

Security is a platform concern, not a feature added at the end. The architecture assumes:

• Secrets live in environment variables, never source control.
• Authentication and authorization are centralized.
• Uploaded files are isolated and validated.
• Generated reports are treated as sensitive artifacts.
• Audit logs must capture important administrative and AI actions.
• Connectors must define data access boundaries clearly.
• Public web assets are separated from application source and storage.
• Web servers must use public/ as the document root. A root .htaccess denies accidental direct serving of repository files when Apache is used.

AI Governance Philosophy

AI outputs must be explainable, traceable, and reviewable. The platform will separate raw inputs, deterministic metrics, prompt versions, model configuration, and generated outputs so administrators can understand why a recommendation was created.

Governance includes prompt lifecycle metadata, prompt hash verification, model registry metadata, audit records, token and cost accounting, replay references, explainability placeholders, execution policies, and controls for future human review.

Prompt Versioning Philosophy

Prompts are treated as governed platform artifacts. Future prompt execution should record:

• Prompt identifier
• Prompt version
• Prompt hash
• Model name and configuration
• Input references
• Output references
• Execution cost
• Execution timestamp
• Actor or system that initiated the run

This allows prompt changes to be reviewed, reproduced, and audited over time.

Cost Tracking Philosophy

AI usage must be measurable. The platform tracks model usage and actual calculated AI cost by use case, connector, tenant or account, prompt version, model, and report workflow where applicable.

Cost visibility is required for responsible scaling, customer pricing, operational budgeting, and governance review.

Long-Term Vision

Executive Intelligence Engine will become a reusable open-source foundation for governed AI business applications. The platform should eventually support multiple industries, multiple use cases, data connectors, governed prompt libraries, executive scorecards, generated reports, PDF output, email delivery, REST APIs, authentication, administration, and future plugins.

Known Limitations

• The RC1 workflow uses fictional retail data for one active demonstration company.
• Live analysis requires a configured OpenAI API key and approved GPT-5.6 model; synthetic output is test-only.
• Production connector synchronization, write-back operations, PDF generation, and email delivery are deferred.
• Persistent sessions, MFA, SSO, and full multi-organization product workflows are post-hackathon work.

Post-Hackathon Roadmap

• Production-grade connector synchronization and credential operations.
• Multi-organization onboarding and workspace administration.
• Persistent session storage, MFA, and SSO.
• Report generation, PDF delivery, and executive email workflows.
• Broader industry templates while retaining governed prompts, auditability, and cost controls.
• Performance, resilience, and load testing for production deployment.

License

License terms are pending and will be finalized before public release.