Skip to content

INDEX.md

Latest commit

 

History

History
77 lines (63 loc) · 9.61 KB

INDEX.md

File metadata and controls

77 lines (63 loc) · 9.61 KB
Raw

ForgeAI Master Architecture, Governance & Technical Documentation Suite

Welcome to the ForgeAI Master Documentation & Governance Suite.

ForgeAI is an Operating System for Software Engineering that enables human engineers and autonomous AI agents to collaboratively plan, design, build, test, review, deploy, monitor, and continuously evolve software systems.

🏛️ Engineering Governance & Foundation Suite (/docs)

Section Document Title Primary Roles Key Focus Areas
00 Project Foundation & Layout Platform Architect, Tech Writer Repository layout, docs directory structure, naming conventions & markdown standards
01 ForgeAI Constitution CTO, Principal Architect, All Roles Supreme vision, mission, core values, engineering philosophy & non-negotiables
02 Comprehensive Engineering Standards Staff Engineer, Security Lead PHP 8.5/Pint/Larastan L8, Vue 3/Wayfinder/Tailwind v4, DB, Pest v4 & AI prompt standards
03 End-to-End Development Workflow Engineering Manager, Product Lead 12-Stage development lifecycle, inputs, outputs, approval gates & quality checks
04 Git Workflow & Release Strategy DevOps Architect, Staff Engineer Branching model, Conventional Commits, PR gates (ci:check), SemVer 2.0 & releases
05 Definition of Done (DoD) QA Lead, Security Lead, Staff Engineer 10 Verification categories: Functional, Pest tests, Docs, Security, Performance, Accessibility, Evals
06 Information Architecture & UX UX Architect, Product Lead UI navigation hierarchy, 10 primary workspace screens & split-pane agent workspaces
07 Design System Standards UX Architect, Frontend Engineer Aesthetic pillars, Inter/JetBrains Mono typography, Tailwind v4 HSL palette & Reka UI
08 Technical Backlog Framework Product Manager, PM Agent 7-Tier Work Breakdown Structure (Vision -> Initiative -> Epic -> Feature -> Story -> Task -> Subtask)
09 Agent Specifications Roster AI Systems Architect, Staff Engineer Agent specification template & 10 Specialist Agent personas (PM, Architect, Devs, SecOps, QA)
10 Standard Tool Registry AI Systems Architect, Platform Engineer Standard ToolDefinition PHP interface & specifications across 13 tool categories
11 Prompt Library Standards AI Systems Architect, Tech Writer Version-controlled .prompts/ YAML+Markdown structure & specialist system prompts
12 Canonical Implementation Blueprint Principal Architect, CTO Step-by-step idea-to-production lifecycle blueprint, sequence flows & approval gates

📚 Master Product & Architecture Blueprint Suite

Section Document Title Primary Focus Areas
00-Overview Overview & Strategic Foundation Vision, mission, product goals, design philosophy & ubiquitous glossary
01-PRD Product Requirements Document (PRD) Problem statement, personas, user journeys, functional/NFRs, scope boundaries
02-DDD Domain-Driven Design Specification 10 Bounded Contexts, Aggregates, Entities, Value Objects, Domain Events & Context Map
03-ADRs Architecture Decision Records Index Master ADR index and 10 detailed decision records (ADR-0001 through ADR-0010)
04-System System Architecture Specification C4 system topology, Inertia v3 SSE streaming, Horizon queues & hybrid vector search
05-Modules Modular Architecture Specification 14 Core Domain Modules: Core, AI, Agent, Workspace, Projects, Planning, Graph, etc.
06-Graph Engineering Graph & Reasoning Engine Connected property graph schema, recursive CTE query engine & agent context reasoning
07-AgentFramework Collaborative Multi-Agent Framework Multi-agent state machine, context compaction, tool sandboxing & 10 Specialist Agent personas
08-DataArch Data Architecture & Logical Model Logical entity models, aggregate boundaries, multi-tenant query scopes & token ledgers
09-APIStrategy API Strategy & MCP Gateway Wayfinder typed actions, REST/SSE APIs, Webhook engine & Bi-directional MCP Gateway
10-SecurityArch Security Architecture & Governance Zero-Trust security, Passkeys/Fortify, RBAC/ABAC matrix, Prompt Injection shields & Secrets
11-Standards Development Standards & Quality Directory conventions, PHP 8.5/Pint/Larastan level 8 standards & Pest v4 test matrix
12-Specs Feature Specification Matrix Feature specification template & per-module functional specification matrices
13-Roadmap Phased Implementation Roadmap 6-Phase execution timeline, milestones, dependencies, risks & exit criteria

🏛️ Architectural Decision Records (ADRs)

ADR ID Title Status Date
ADR-0001 Core Tech Stack: Laravel 13, Inertia v3, Vue 3, Tailwind v4 Accepted 2026-07-24
ADR-0002 Standardizing AI Engine on First-Party laravel/ai SDK Accepted 2026-07-24
ADR-0003 Adoption of Event-Driven Modular Monolith Architecture Accepted 2026-07-24
ADR-0004 PostgreSQL 16 + pgvector as Primary Data & Vector Engine Accepted 2026-07-24
ADR-0005 Engineering Graph Storage via PostgreSQL Recursive Adjacency Models Accepted 2026-07-24
ADR-0006 Queue Topology & Priority Levels via Redis Horizon Accepted 2026-07-24
ADR-0007 Bi-Directional Model Context Protocol (MCP) Gateway Integration Accepted 2026-07-24
ADR-0008 Authentication Engine: Laravel Fortify + WebAuthn Passkeys Accepted 2026-07-24
ADR-0009 Subprocess & Isolated Container Sandboxing for Agent Tools Accepted 2026-07-24
ADR-0010 Server-Sent Events (SSE) Streaming for Agent Outputs & Graphs Accepted 2026-07-24

🛠️ Technology Stack Reference

  • Backend Framework: Laravel 13 (PHP 8.5)
  • AI Infrastructure: laravel/ai (v0.10+ SDK)
  • Frontend Architecture: Inertia.js v3 + Vue 3 (Composition API, <script setup>)
  • Route Resolution: @laravel/vite-plugin-wayfinder / laravel/wayfinder
  • Authentication: laravel/fortify + @laravel/passkeys (WebAuthn / Passkeys)
  • Database & Search: PostgreSQL 16 + pgvector HNSW indexes
  • Asynchronous Execution: Redis Horizon Queues (critical, ai-inference, tool-execution)
  • Testing & Evals: Pest v4 (Unit, Feature, Arch, Evals)
  • Code Standards: Laravel Pint, Larastan Level 8+