System Architecture & Principles
Relevant source files
The following files were used as context for generating this wiki page:
NeXifyAI is a cognitive enterprise platform that provides autonomous AI agents for business automation in the D/A/CH region. The system operates on a governance-first model where all runtime actions pass through automated quality gates and structural validation before execution.
The platform integrates a multi-layered technical stack including a React frontend, a FastAPI backend, and a specialized AI runtime called the Hermes Gateway. Central to its operation is the "Brain"—a Qdrant-based vector knowledge base that persists decisions, memories, and organizational logic to ensure long-term consistency and learning across all autonomous agents.
Sources: ARCHITECTURE.md:3-9, nexifyai-github-prompt.prompt.yml:256-270
Core Architectural Layers
The system follows a distributed service architecture where frontend applications communicate with a centralized API server, which in turn orchestrates AI agents and long-running workflows.
System Stack Overview
| Layer | Technology | Function |
|---|---|---|
| Frontend | React 18 / Next.js 14 | User interfaces for landing pages and admin dashboards. |
| API Server | FastAPI | RESTful entry point for system requests and orchestration. |
| Workflows | Temporal.io | Manages asynchronous business logic with fault tolerance. |
| AI Runtime | Hermes Gateway | Executes agent profiles and manages cognitive processes. |
| Brain | Qdrant | Stores 4096-dim vector embeddings for organizational memory. |
| Database | Supabase (PostgreSQL) | Handles relational data, tenant isolation, and audit logs. |
Sources: ARCHITECTURE.md:12-24, SETUP.md:73-82
Component Relationship Diagram
This diagram shows the flow of data from the user interface through the API orchestration layer to the persistent storage and AI execution engines.
Sources: ARCHITECTURE.md:27-44, SETUP.md:73-82
Governance & Quality Gates
NeXifyAI enforces a "Governance-first" principle where the platform validates its own runtime state before accepting or executing work. The system uses a specialized agent, the Senior Quality Auditor, to enforce these standards.
The 7 Quality Gates
Before any system, deployment, or agent execution reaches production, it must pass seven mandatory checks:
- Documentation: Requires architecture specs, API docs, and decision records.
- Testing: Demands unit test coverage ≥80% for P0 systems.
- Security: Validates secret management, port status, and authentication.
- Architecture: Ensures alignment with the 12-System model and scaling plans.
- Performance: Enforces latency targets (<200ms p95 for APIs).
- Workflow: Verifies order tracking and context enrichment from the Brain.
- Agent Quality: Validates agent profile length (>4000 chars) and Brain-First mandates.
Sources: services/api/agents/brain_agents/senior-quality-auditor.md:18-72, ARCHITECTURE.md:46-52
Audit Scoring and Escalation
The system calculates a total score based on the average of the 7 gates.
- ≥0.85: Approved for production.
- 0.70 - 0.84: Conditional approval with required fixes.
- <0.50: Blocked. The orchestrator halts the affected system and notifies the CEO.
Sources: services/api/agents/brain_agents/senior-quality-auditor.md:86-93
Order Workflow & Production Pipeline
No work occurs in the platform without an explicit order. The Order Workflow Specialist manages the full lifecycle of every task from discovery to completion.
Order Lifecycle Sequence
The sequence diagram below illustrates how a task moves from creation through expert matching and quality review.
Priority and Routing Matrix
Tasks are routed based on priority levels (P0-P3) which define the required actors and escalation timeouts.
| Priority | Who Executes | Reviewer | Timeout |
|---|---|---|---|
| P0 | CEO + Domain Expert | CEO | 15 Minutes |
| P1 | Domain Expert | Senior QA | 60 Minutes |
| P2 | Expert (Auto-assign) | Review Agent | 4 Hours |
| P3 | Scheduled Batch | Review Agent | 24 Hours |
Sources: services/api/agents/brain_agents/order-workflow-specialist.md:30-37
Development & Deployment Principles
The platform adheres to strict "Architecture Lockdown" rules and "Privacy by Design" standards, particularly for the D/A/CH market.
Core Development Rules
- Brain-First Mandate: Agents must query the Brain before acting and store results after.
- Tenant Isolation: Every tenant (customer) receives an isolated GitHub repo, Vercel project, and RLS-protected Supabase schema.
- Zero Trust: No internal network segment is assumed safe; every endpoint requires authentication (JWT or X-Internal-Auth).
- Self-Healing: The runtime monitors for "drift" and attempts auto-repair within governance bounds.
Sources: ARCHITECTURE.md:5-9, CLAUDE.md:12-21, services/api/agents/brain_agents/senior-quality-auditor.md:45-51
Execution Workflow (CLAUDE.md)
You must follow these steps for every technical task:
- Understand Goal: Execute a Brain-query before starting.
- Load Context: Read rules, skills, and agent definitions.
- Check Inventory: Verify existing files to avoid duplication.
- Decompose: Break the task into entries in the Task Registry.
- Implement: Write code with linting and tests.
- Verify: Perform the review loop (Security, Quality, Completeness).
- Persist: Update the Brain and agent memory.
Sources: CLAUDE.md:6-16
Summary
NeXifyAI operates as a highly disciplined autonomous system where every action is audited, documented, and stored in a central cognitive memory. By combining Temporal workflows for reliability, Qdrant for memory, and a multi-gate governance model, the platform ensures enterprise-grade stability and continuous learning. All components are strictly isolated to meet D/A/CH compliance and GDPR standards.