Skip to content

architecture-design.md

Latest commit

 

History

History
236 lines (204 loc) · 15.3 KB

architecture-design.md

File metadata and controls

236 lines (204 loc) · 15.3 KB
Raw

Nexus Forge — Architecture Design Document

1. Architectural Goals

The architecture of Nexus Forge optimizes for long-term maintainability, high modularity, testability, and strict independence from external vendors or volatile AI ecosystems. By keeping the core planning logic decoupled from input/output mechanisms and external data formats, the architecture guarantees that the system can evolve its capabilities without requiring rewrites of its business rules.

2. Architecture Principles

The architecture is strictly guided by the following principles:

  • Explicit Dependencies: Components must explicitly declare what they require to function.
  • Single Responsibility: Every module, class, or component has exactly one reason to change.
  • Dependency Inversion: High-level policy must never depend on low-level details. Both must depend on abstractions.
  • Replaceable Infrastructure: I/O, AI providers, and knowledge parsers must be swappable without modifying the core.
  • Stateless Application Services: The system maintains no long-lived state between distinct execution runs in Version 1.
  • Deterministic Core Logic: Given the exact same context, intent, and metadata, the Core Engine must produce the exact same plan.
  • Traceable Recommendations: Every output must map directly back to a specific structured input.
  • Immutable Business Rules: Core domain logic must never be bypassed by infrastructure or presentation layers.

3. Architectural Drivers

  • Functional Drivers: The system must deterministically extract repository context, interpret engineering intent, query structured knowledge, and synthesize reproducible execution plans without modifying user code.
  • Quality Attribute Drivers: The architecture must guarantee high testability, local-first offline capability, sub-15-second performance for plan generation, and absolute vendor independence.
  • Business Drivers: The project must remain 100% free and open-source, with no mandatory paid API usage, supporting high adoption rates among budget-constrained developers.
  • Technical Drivers: The system must seamlessly ingest existing agentic-awesome-skills JSON metadata and remain robust against schema variations.

4. Architecture Style

Selected Style: Modular Monolith utilizing Clean Architecture.

Justification: Version 1 operates locally as a single-user planning engine. A Modular Monolith minimizes deployment complexity and eliminates the network overhead, distributed failure modes, and eventual consistency issues inherent to microservices.

Clean Architecture ensures that the core domain (knowledge discovery, recommendation, and planning) is completely isolated from infrastructure concerns (JSON parsing, file system access, external AI models). This strict separation protects the core business rules from technological churn.

5. Architectural Invariants

These rules must NEVER be violated under any circumstances:

  • The Core Domain depends on nothing external.
  • Business rules are deterministic.
  • Infrastructure is fully replaceable without business logic changes.
  • The Repository is strictly read-only.
  • Every recommendation is traceable to a Knowledge Source.
  • Execution Plans always reference structural evidence.
  • Infrastructure details (exceptions, file paths, JSON schemas) must never leak into the Core Domain.

6. Context Diagram (C4 Level 1)

Conceptually, the system boundary involves the following entities:

  • Developer: Submits an engineering goal and receives an execution plan.
  • Nexus Forge (System): The core intelligence platform bridging intent and execution.
  • Local Repository: The developer's project files, accessed strictly in a read-only capacity.
  • Knowledge Sources: Existing structured JSON metadata containing engineering patterns.
  • Optional AI Providers: External or local reasoning engines used to enhance intent parsing or ranking.

7. Container View (C4 Level 2)

The Modular Monolith is logically divided into the following containers:

  • User Interface: Captures developer intent and presents the final execution plan.
  • Nexus Forge Core Engine: The central orchestrator that houses the business logic for plan synthesis and recommendation ranking.
  • Context Analyzer: Interacts with the local repository to build the conceptual Repository Context.
  • Knowledge Gateway: Queries and translates external structured JSON metadata into internal domain entities.
  • AI Gateway: Interfaces with local or remote AI models if heuristic reasoning is required.

8. Component View (C4 Level 3)

  • Intent Processor Component: Interprets the raw user goal.
  • Context Manager Component: Orchestrates the extraction and validation of repository state.
  • Knowledge Matcher Component: Discovers relevant skills and bundles.
  • Ranking Engine Component: Evaluates and prioritizes discovered knowledge.
  • Plan Synthesizer Component: Constructs the final reproducible roadmap.

9. Architectural Boundaries

The architecture enforces strict boundaries using concentric layers:

  1. Core Domain: Business entities (Execution Plan, Recommendation, Repository Context).
  2. Application Layer: Use cases (Generate Plan, Revise Plan, Extract Context).
  3. Interface Layer: Input/output adapters (Controllers, Presenters).
  4. Infrastructure Layer: Concrete implementations (File system readers, JSON parsers).
  5. External Systems: The Local Repository, the JSON Knowledge Source, Optional AI APIs.

10. Dependency Rules

  • The Core Domain may only depend on itself.
  • The Application Layer may only depend on the Core Domain.
  • The Interface Layer may depend on the Application Layer and Core Domain.
  • The Infrastructure Layer may depend on the Interface and Application layers (Dependency Inversion).
  • Prohibited Dependencies: The Core Domain must NEVER depend on Infrastructure. The Application Layer must NEVER depend on the User Interface.

11. Component Dependency Graph

Conceptual allowed dependencies:

  • CLI Controller → Application Use Case
  • Application Use Case → Core Domain Entities
  • Application Use Case → Outgoing Port Interfaces
  • Repository Adapter → Outgoing Port Interfaces (Implementation)
  • Knowledge Adapter → Outgoing Port Interfaces (Implementation)
  • Plan Synthesizer → Recommendation Engine
  • Recommendation Engine → Knowledge Matcher
  • Prohibited: Knowledge Matcher → Repository Adapter. Application Use Case → CLI Controller.

12. Runtime Execution Flow

The complete request lifecycle follows this deterministic flow:

  1. Developer: Initiates the tool with an intent.
  2. Intent Request: Interface layer captures raw input.
  3. Application Use Case: Central orchestrator begins execution.
  4. Repository Context Service: Dispatches request to Repository Adapters to abstract the project state.
  5. Knowledge Service: Queries Knowledge Adapters using context and intent.
  6. Recommendation Service: Ranks retrieved knowledge strictly against domain constraints.
  7. Planning Service: Synthesizes ranked knowledge into an Execution Plan entity.
  8. Presenter: Formats the Execution Plan into the output structure.
  9. Execution Plan: Rendered to the Developer.

13. Component Interaction Rules

Explicit rules for component interactions:

  • Application Use Case: May orchestrate all internal services. May NOT perform raw I/O.
  • Context Manager: May call Repository Outgoing Ports. May NOT call Knowledge Ports.
  • Knowledge Matcher: May call Knowledge Outgoing Ports. May NOT access project files.
  • Ranking Engine: May consume Knowledge entities and Context entities. May NOT call external APIs.
  • Plan Synthesizer: May receive ranked recommendations. May NOT call repository adapters.
  • Knowledge Gateway (Adapter): May parse JSON files. May NOT access presentation components.

14. Port Contracts

To enforce decoupling, the Application Layer defines explicit Ports:

Context Extraction Port

  • Type: Outgoing
  • Responsibilities: Extract abstract structure from the repository.
  • Expected Inputs: Target path/URI.
  • Expected Outputs: Structured Context Data.

Knowledge Lookup Port

  • Type: Outgoing
  • Responsibilities: Query available skills based on parameters.
  • Expected Inputs: Intent tags, architectural constraints.
  • Expected Outputs: Collection of Knowledge Data.

Planning Execution Port

  • Type: Incoming
  • Responsibilities: Provide the entry point for generating plans.
  • Expected Inputs: Raw text intent, project path.
  • Expected Outputs: Execution Plan Entity.

15. Adapter Taxonomy

Infrastructure is strictly categorized by responsibility:

  • Input Adapters: Capture user requests (e.g., CLI parsing).
  • Output Adapters: Format and render results (e.g., Markdown presenter).
  • Repository Adapters: Read and parse local file systems safely.
  • Knowledge Adapters: Parse specific structured JSON metadata schemas.
  • AI Adapters: Communicate with reasoning engines via API.
  • Configuration Adapters: Load and inject environmental settings.
  • Persistence Adapters: Save cached metadata or logs (if utilized).

16. Responsibility Matrix

Component Primary Responsibility Owns Uses Must Never Know About
Application Use Case Orchestrating the plan generation flow Flow logic Domain Services, Ports CLI, JSON formatting, File paths
Context Service Abstracting project state Context validation Repository Port Knowledge schemas
Knowledge Service Discovering engineering patterns Query formulation Knowledge Port Repository structure
Ranking Service Evaluating architectural fit Scoring logic Context, Knowledge File System
Plan Synthesizer Constructing the final roadmap Roadmap logic Ranked Recommendations Adapters, Infrastructure
Presenter Formatting output for the user Presentation logic Execution Plan Entity Domain services, Adapters
Repo Adapter Reading files from disk I/O safety Native filesystem Domain rules, Ranking logic

17. Error Propagation Strategy

Failures move through the architecture predictably, preventing domain leakage:

  1. Infrastructure Failure: (e.g., File permission denied, JSON malformed).
  2. Adapter Translation: The Adapter catches the raw exception and translates it into a discrete Domain Error (e.g., RepositoryAccessDenied, MalformedKnowledgeSource).
  3. Application Result: The Application Use Case halts processing and returns an Error Result containing the Domain Error.
  4. Presentation: The Presenter maps the Domain Error to a human-readable failure message. Note: Infrastructure exceptions (stack traces, raw API errors) must NEVER leak into the Core Domain.

18. Architectural Decision Matrix

When the system must make conceptual architectural choices (e.g., Ranking), decisions are driven by:

  • Repository Context: Existing constraints (language, framework) heavily penalize conflicting knowledge.
  • Engineering Goal: The primary semantic match determines baseline relevance.
  • Knowledge Evidence: The completeness of the JSON metadata acts as a weighting factor.
  • Business Rules: Immutable rules immediately filter out violations (e.g., paid APIs if constrained).
  • Constraints: Budget, offline status, and OS requirements filter candidate skills.

19. Core Subsystems

  • Repository Context: Safely constructs an abstract representation of a project.
  • Knowledge Discovery: Efficiently queries structured metadata.
  • Recommendation Engine: Applies business rules to score and rank architectural patterns.
  • Execution Planning: Assembles discrete tasks into a roadmap.
  • Evidence & Traceability: Ensures every task traces back to a specific metadata source.
  • Configuration: Manages user preferences independently of business logic.
  • User Interaction: Handles presentation of data and capture of input.

20. Data Flow

  1. Repository state is read by the Context Analyzer.
  2. Context is mapped to a Domain Entity.
  3. Intent is captured from the Interface Layer.
  4. Knowledge is retrieved via the Knowledge Gateway.
  5. Ranking is performed on the retrieved Knowledge entities.
  6. Planning occurs as the Synthesizer formats recommendations.
  7. Output is generated and rendered for the Developer.

21. Extension Points

  • Knowledge Providers: New metadata formats can be supported by creating a new Knowledge Adapter.
  • AI Providers: New LLMs can be supported by implementing the AI Adapter.
  • Repository Analyzers: Support for new languages added via new Repository Adapters.
  • Output Renderers: Render to Markdown, HTML, or JSON by adding new Output Adapters.

22. Architectural Decisions

  • ADR-001: Modular Monolith over Microservices
    • Context: Local-first developer tool.
    • Decision: Build a Modular Monolith.
    • Consequences: Simplifies deployment, ensures offline capability.
  • ADR-002: Clean Architecture for Domain Isolation
    • Context: System must remain immune to changes in AI technologies or JSON schemas.
    • Decision: Enforce strict dependency inversion.
    • Consequences: Guarantees long-term maintainability.
  • ADR-003: Adapter-based Context Ingestion
    • Context: System must analyze varied project structures.
    • Decision: Isolate all file system parsing behind Adapters.
    • Consequences: Core planner never touches a file system directly.

23. Cross-Cutting Concerns

  • Logging: Centralized tracking of intent and plan generation.
  • Configuration: Environment-agnostic configuration injected at startup.
  • Error Handling: Standardized error boundaries (see Error Propagation Strategy).
  • Security: JSON parsers strictly sandboxed.
  • Privacy: Telemetry disabled by default.
  • Validation: All inputs validated at the Infrastructure boundary.
  • Observability: Traceability IDs included in all outputs.
  • Documentation: Architecture design fully documented.

24. Quality Attribute Scenarios

  • Maintainability: Schema changes only affect specific Infrastructure Adapters; zero Domain files change.
  • Performance: Context Analyzer parallelizes file system reads to meet SLA.
  • Reliability: AI Gateway timeouts fall back to deterministic local metadata.
  • Scalability: Knowledge Gateway utilizes local indexing for O(1) lookups.
  • Offline Capability: System falls back to locally cached Knowledge and models.
  • Vendor Independence: Commercial AI APIs can be swapped without modifying the Core Engine.
  • Testability: 100% of business logic is unit-testable using in-memory mocks.

25. Architectural Risks

  • Risk: Complex repository context extraction leaking into the Core Domain.
    • Mitigation: Enforce strict Data Transfer Objects (DTOs) at the Application boundary.
  • Risk: High memory consumption during parsing of massive Knowledge Sources.
    • Mitigation: Employ lazy loading and streaming JSON parsers in Knowledge Adapters.

26. Future Evolution

Version 1 is designed to evolve smoothly:

  • Moving from a CLI tool to a GUI extension requires only building a new Output Adapter.
  • Expanding to multi-repository planning involves extending the Repository Context entity and Repository Adapter, utilizing existing Extension Points.