Project Philosophy
The Overarching Directive for All Development in EDDI
This document defines the foundational principles that govern every architectural decision, feature implementation, and design trade-off across the EDDI ecosystem. Every contributor — human or AI — must internalize these principles before writing code.
This is not a technical specification. Implementation details belong in
architecture.mdandAGENTS.md. This document answers why — those documents answer how.
Identity Statement
EDDI is the "Grown-Up" Enterprise AI Orchestrator.
While competitors were built for rapid prototyping and are now frantically reverse-engineering enterprise qualities into architectures that resist them, EDDI approaches from the opposite direction: a deterministic engine built to safely govern non-deterministic AI — from single agents to multi-agent orchestration.
EDDI's competitive moat is structural, not feature-based. It emerges from the combination of:
JVM-native concurrency — true parallelism without language-level barriers
Configuration-driven logic — agent behavior is data, not compiled code
Strict pipeline architecture — deterministic execution of probabilistic components
Multi-agent orchestration — coordinated reasoning across agent groups
Security & compliance by default — baked into the architecture, not bolted on
The Nine Pillars
Pillar 1: Configuration Is Logic, Java Is the Engine
"Agent behavior belongs in configuration. Code builds the components that read and execute those configurations."
EDDI is a config-driven engine, not a monolithic application. The intelligence of an agent — its routing rules, API calls, LLM prompts, output templates — is defined in versioned JSON documents. Code provides the infrastructure components that interpret and execute those configurations at runtime.
When designing a new feature, always ask: "Should this be configurable by the agent designer?" If yes, expose it as a config field with sensible defaults — don't hardcode behavior.
Why this matters: Competitors that embed logic in code suffer from deployment friction (every change requires recompilation), security vulnerabilities (dynamic code execution), and operational opacity (logic can't be versioned or rolled back independently).
The escape hatch: When an agent designer genuinely needs custom code, EDDI provides bilateral protocol integration — it can both expose its capabilities to and consume capabilities from external services. Custom logic runs in isolated containers outside the EDDI perimeter.
Pillar 2: Deterministic Governance of Non-Deterministic AI
"The engine is strict so the AI can be creative."
LLMs are inherently probabilistic — they hallucinate, loop infinitely, and burn through token budgets unpredictably. EDDI's role is to provide deterministic guardrails around this non-determinism: budget controls, error containment, governance controls, and immutable audit trails.
Concrete expectations:
Every tool call must pass through rate limiting, caching, and cost tracking — no unmetered execution paths
Framework errors must never leak into LLM conversation history — map failures to structured signals in the pipeline
Multi-agent interactions must be serialized through a governance mechanism — no concurrent, uncoordinated writes to shared state
External tool integrations must be classified by risk level, with state-changing operations requiring explicit approval
Pillar 3: The Engine, Not the Application
"EDDI provides the components. The admin configures the intelligence."
EDDI is middleware — it sits between user-facing channels and AI providers. It does not contain business logic; it contains the machinery to execute business logic defined as configuration. Adding a new capability means adding a new component type, not modifying existing ones.
Why this matters: This architecture enables multi-tenancy (same engine, different agents), instant iteration (edit config, not code), and clean extensibility (auto-discovery, no registration).
Anti-patterns:
Building custom schedulers or background job infrastructure — reuse the existing scheduling framework
Creating new pipeline components for session-level concerns — extend the session lifecycle instead
Calling components directly from other components — use event-based orchestration for all inter-component communication
Pillar 4: Security & Compliance as Architecture, Not Afterthought
"If a security measure can be bypassed by changing a configuration, it is not a security measure."
Security and regulatory compliance are enforced at the architectural level: the type system, the classpath, the network topology, and startup checks. They are never delegated to the LLM, the prompt, or the admin's good judgment.
Security principles:
No dynamic code execution — ever. Expression evaluation uses safe, sandboxed parsers
No plaintext secrets in storage — all credentials use vault references resolved at runtime
No trusting LLM output for access control — tenant isolation is enforced by code, not by prompt
External URLs are validated against SSRF — private IPs and internal hostnames are blocked
Agent exports are sanitized — secrets are scrubbed before packaging
Compliance principles:
Data subject rights (erasure, portability, restriction) must be enforceable through the architecture, not just documented
AI decision audit trails must be immutable and write-once — they are evidence, not logs
Compliance requirements must be enforced at startup — if a required capability is missing, the system should fail fast rather than run without it
Pillar 5: Enterprise-Grade Concurrency
"The JVM's concurrency model is our unfair structural advantage."
Language-level concurrency barriers (Python's GIL, Node.js's single-threaded event loop) are fundamental obstacles to scaling multi-agent AI workloads. EDDI leverages the JVM's thread model to achieve true parallelism without blocking, without heartbeat starvation, and without the serialization panics that plague competitors.
Principles:
Pipeline components are stateless singletons — all conversational state lives in a dedicated memory object
No raw infrastructure objects (DB connections, HTTP clients) in conversational state — transient resources are scoped appropriately
No unbounded in-memory collections — all caches have strict size limits and TTLs
Messaging infrastructure threads must never be blocked by application logic
Pillar 6: Transparent Observability
"If you can't see why the AI made a decision, you can't fix it, audit it, or trust it."
Every conversation turn must produce a complete, immutable trace of exactly what happened: the compiled prompt, the retrieved context, the tool calls, the memory state, and the cost. This is not debugging infrastructure — it is the product.
Observability serves two masters: developers who need to understand why an agent behaved a certain way, and regulators who need evidence of what the AI decided and why. Both must be served by the same infrastructure — not by separate logging systems.
Vision: A "Time-Traveling IDE" experience — step-through replay of any conversation turn with exact compiled prompts, memory state snapshots, and pause/edit/resume controls.
Pillar 7: Progressive Disclosure in UX
"Easy things should be easy. Hard things should be possible."
The management UI must serve two audiences simultaneously: business users who want visual forms and guided wizards, and power users who want raw configuration editing with validation and autocomplete. Both views are identical state representations — editing one updates the other.
Principles:
No spaghetti node graphs — use structured layouts with wires only for macro-routing
No modals — use side-sheet inspectors so the main view remains visible
Trusted vs. untrusted data must be visually distinguishable
Surface actionable metrics (resolution rate, cost per agent), not vanity metrics
Pillar 8: Persistent Memory & Cross-Session Intelligence
"An agent that forgets everything between sessions is not an intelligent agent."
Conversational intelligence requires memory that outlives individual sessions. EDDI provides a layered memory architecture where short-term pipeline data, medium-term conversation properties, and long-term persistent memories each serve distinct purposes — and the boundaries between them are explicit, configurable, and secure.
Principles:
Memory has two audiences: pipeline components see everything; the LLM sees only a windowed, curated view. Context management strategies must respect this distinction
Persistent state is a session concern — it is loaded at session start and saved at session end, not managed by pipeline components
Memory visibility is enforced at the storage level, not by prompt filtering — an agent cannot leak cross-tenant memories through prompt tricks
Background memory operations (consolidation, summarization) use the platform's scheduling infrastructure, not custom jobs
Failed pipeline data must be containable — error output should not pollute future LLM context
Pillar 9: Agent Portability & Sync
"An agent locked to one instance is an agent locked to one vendor."
Agent configurations must be fully portable — exportable, importable, diffable, and synchronizable between instances without loss of fidelity. This is the foundation of multi-environment workflows (dev → staging → production) and prevents vendor lock-in.
Principles:
Sync operations are always pull-based from the target's perspective — the source is never modified
Content-identical resources are detected and skipped automatically — no unnecessary version churn
Secrets are never included in exports — they are scrubbed at the export boundary
Sync must support preview-before-apply — operators must see exactly what will change before committing
Partial failures in batch operations don't roll back successful ones — each resource syncs independently
Strategic Positioning
EDDI occupies a unique position as the only JVM-native, config-driven AI orchestration platform in a market dominated by Python/Node.js solutions. While competitors offer either visual orchestration (without enterprise qualities) or enterprise frameworks (without visual configuration), EDDI provides both.
Three strategic pitches:
Escape the Prototype Trap — transition fragile prototypes to robust JVM production with true multi-agent orchestration
Agility Through Configuration — update AI logic in seconds without recompilation, sync changes across environments instantly
Cloud-Native Scale — JVM virtual threads deliver minimal footprint and maximum throughput without the concurrency compromises of competing language runtimes
Document Governance
This document is the supreme directive for EDDI development. When a technical decision conflicts with these principles, the principles win. When a new feature doesn't fit within these pillars, either the feature must be redesigned or a new pillar must be proposed and approved.
Versioning: This document evolves with the project. Changes require explicit approval from project leadership and must be documented in the changelog.
Last updated
Was this helpful?