# zyra-v23/chatprd architecture

> Architecture diagram of the GitHub repository zyra-v23/chatprd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zyra-v23/chatprd
- Repository: https://github.com/zyra-v23/chatprd

## Overview

##### Main Components
- System Core: Represented by src/core/system.js, this is the central coordinator that initializes and manages all services and components.
- Interfaces: Located in src/core/interfaces, these define contracts for AI providers, export providers, plugins, service interfaces, and storage providers.
- Adapters: Found in src/core/adapters, these are concrete implementations (e.g., ClaudeAdapter, FilesystemAdapter, ExportAdapter) that plug into the interfaces to provide actual functionality.
- Models: In src/core/models, they encapsulate the domain entities like concept, discussion, idea, and prd.
- Services: In src/core/services, these implement the business logic (e.g., discussion-service, ideation-service, prd-service) that actually drives the application’s processes.
- Utilities: In src/core/utils, helper functions for configuration, error handling, logging, and factory methods set up the environment and manage dependencies.
- Plugins: Located in src/plugins, these extend functionality to external systems such as Cursor IDE (cursor-plugin.js) and Lovable (lovable-plugin.js).
- Entry Points: src/index.js and src/core/system.js serve as the main entry points for application initialization.

##### Relationships and Interactions
- The System module (system.js) acts as the orchestrator; it uses the factory (from utils) to instantiate required adapters and services based on configuration.
- Interfaces define the contracts that every adapter and service must follow. Adapters in the core plug into these interfaces to interact with external AI providers, storage mechanisms, and export formats.
- Business logic in Services consumes models (e.g., PRD, idea) and communicates with adapters to incorporate external functionalities.
- Plugins integrate with the core system to provide platform-specific features. They register themselves (following PluginInterface) with the System so they can be invoked when needed.
- Configuration details (via .env or configuration objects) determine which providers and plugins are activated.

##### Architectural Patterns and Design Principles
- Modular Architecture: The separation into core and plugins demonstrates extensibility.
- Dependency Inversion: Through interfaces and adapters, the system remains agnostic to the specific implementations of providers.
- SOLID Principles: Each component (adapters, services, interfaces) is responsible for a specific aspect, enhancing maintainability.
- Extensibility: The use of plugins means new integrations can be added with minimal changes to the core architecture.

##### Specify the Use of Technologies and Tools
- JavaScript/Node.js is the primary technology.
- The system integrates with external APIs (e.g., Anthropic’s Claude) and uses the filesystem for persistent storage via the FilesystemAdapter.
- Platform integration plugins extend functionality to tools like Cursor IDE and Lovable.
- Environment variables and configuration files (like .env.example) are crucial for setting run-time parameters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Block
    CFG("Configuration/Env"):::config
    UTILS_CONFIG("Config.js"):::util
    FACTORY("Factory"):::util
    ENTRY("Entry: index.js"):::entry
    SYS("System (Coordinator)"):::system

    %% Core Interfaces
    INT("Interfaces"):::interface

    %% Adapters Subgraph
    subgraph "Adapters"
        CLAUDE("AI Adapter - Claude"):::adapter
        EXPORT("Export Adapter"):::adapter
        FS("Filesystem Adapter"):::adapter
    end

    %% Services Subgraph
    subgraph "Services"
        DISC_SRV("Discussion Service"):::service
        IDEATION_SRV("Ideation Service"):::service
        PRD_SRV("PRD Service"):::service
    end

    %% Utilities Subgraph (Additional Utilities)
    subgraph "Utilities"
        ERROR_HANDLER("Error Handler"):::util
        LOGGER("Logger"):::util
    end

    %% Models Subgraph
    subgraph "Models"
        CONCEPT("Concept Model"):::model
        DISC("Discussion Model"):::model
        IDEA("Idea Model"):::model
        PRD("PRD Model"):::model
    end

    %% Plugins Subgraph
    subgraph "Plugins"
        CURSOR("Cursor Plugin"):::plugin
        LOVABLE("Lovable Plugin"):::plugin
    end

    %% Configuration Flow
    CFG --> UTILS_CONFIG
    UTILS_CONFIG --> FACTORY
    FACTORY --> SYS

    %% Entry Point to System
    ENTRY --> SYS

    %% System initializing Core Components
    SYS --> INT
    SYS --> CLAUDE
    SYS --> EXPORT
    SYS --> FS
    SYS --> DISC_SRV
    SYS --> IDEATION_SRV
    SYS --> PRD_SRV
    SYS --> ERROR_HANDLER
    SYS --> LOGGER

    %% Services using Models
    DISC_SRV --> CONCEPT
    DISC_SRV --> DISC
    IDEATION_SRV --> IDEA
    PRD_SRV --> PRD

    %% Plugins registering with System
    CURSOR --> SYS
    LOVABLE --> SYS

    %% Styles
    classDef system fill:#f9d3b4,stroke:#333,stroke-width:2px;
    classDef interface fill:#f7e6a2,stroke:#333,stroke-width:2px;
    classDef adapter fill:#b4d7f9,stroke:#333,stroke-width:2px;
    classDef service fill:#c4f9b4,stroke:#333,stroke-width:2px;
    classDef util fill:#d7b4f9,stroke:#333,stroke-width:2px;
    classDef model fill:#f9b4d7,stroke:#333,stroke-width:2px;
    classDef plugin fill:#b4f9d7,stroke:#333,stroke-width:2px;
    classDef entry fill:#f3b4f9,stroke:#333,stroke-width:2px;
    classDef config fill:#b4d7f9,stroke:#333,stroke-width:2px;

    %% Click Events
    click SYS "https://github.com/zyra-v23/chatprd/blob/master/src/core/system.js"
    click INT "https://github.com/zyra-v23/chatprd/tree/master/src/core/interfaces"
    click CLAUDE "https://github.com/zyra-v23/chatprd/blob/master/src/core/adapters/claude-adapter.js"
    click EXPORT "https://github.com/zyra-v23/chatprd/blob/master/src/core/adapters/export-adapter.js"
    click FS "https://github.com/zyra-v23/chatprd/blob/master/src/core/adapters/filesystem-adapter.js"
    click CONCEPT "https://github.com/zyra-v23/chatprd/blob/master/src/core/models/concept.js"
    click DISC "https://github.com/zyra-v23/chatprd/blob/master/src/core/models/discussion.js"
    click IDEA "https://github.com/zyra-v23/chatprd/blob/master/src/core/models/idea.js"
    click PRD "https://github.com/zyra-v23/chatprd/blob/master/src/core/models/prd.js"
    click DISC_SRV "https://github.com/zyra-v23/chatprd/blob/master/src/core/services/discussion-service.js"
    click IDEATION_SRV "https://github.com/zyra-v23/chatprd/blob/master/src/core/services/ideation-service.js"
    click PRD_SRV "https://github.com/zyra-v23/chatprd/blob/master/src/core/services/prd-service.js"
    click UTILS_CONFIG "https://github.com/zyra-v23/chatprd/blob/master/src/core/utils/config.js"
    click ERROR_HANDLER "https://github.com/zyra-v23/chatprd/blob/master/src/core/utils/error-handler.js"
    click FACTORY "https://github.com/zyra-v23/chatprd/blob/master/src/core/utils/factory.js"
    click LOGGER "https://github.com/zyra-v23/chatprd/blob/master/src/core/utils/logger.js"
    click CURSOR "https://github.com/zyra-v23/chatprd/blob/master/src/plugins/cursor-plugin.js"
    click LOVABLE "https://github.com/zyra-v23/chatprd/blob/master/src/plugins/lovable-plugin.js"
    click ENTRY "https://github.com/zyra-v23/chatprd/blob/master/src/index.js"
```
