# mynk322/flowpulse architecture

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

- Interactive diagram: https://gitdiagram.com/mynk322/flowpulse
- Repository: https://github.com/mynk322/flowpulse

## Overview

##### Main Components
- Backend: Represent the ContextCoach Spring Boot application. Highlight its Java packages for controllers, models, services, repositories, configuration, and exception handling. Emphasize service components such as:
- Feature Complexity Analysis (see classes like ComplexityAnalyzer, FeatureClarifier, LLMService, etc.)
- Logging (using Logback with different log files & API request logging)
- Data initialization and MongoDB configuration (MongoConfig, init-db.sh, etc.)
- Frontend: Represent the React/TypeScript application “feature-clarify-analyze”. This includes:
- UI components (various React components like chat-interface, complexity-card, feature-upload, etc.)
- Main pages (Index, FeatureClarification, ComplexityReport, Logs, etc.)
- Services (API communication layer that uses axios, as defined in src/services/api.ts)
- Configuration files (e.g., vite.config.ts, tailwind.config.ts)
- Database: MongoDB plays a vital role in backend persistence. Also note integration with a vector database (based on files such as VECTOR_DB.md, PythonVectorDB.java, and DummyVectorDB.java) which is used for embedding code or querying related content.
- CLI Utilities: A command-line interface exists (under cli and in CLI scripts like feature-complexity-cli.sh) to interact with the backend functionality.
- Logging System: Both frontend and backend log events extensively. Indicate where logs are stored (e.g., logs directory on backend, persistent log storage and viewing components on frontend).

##### Relationships and Interactions
- Workflow that handles feature input, ambiguity detection, query preprocessing, vector database querying, code chunk collection, and finally the complexity analysis performed by the LLM.
- That the backend interacts with an external or local vector database (through interfaces like VectorDB, DummyVectorDB, PythonVectorDB) and utilizes LLM services (LLMService, DummyLLMService), integrated via service classes.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly separated backend and frontend with well-defined responsibilities. The backend uses MVC (with controllers, models, repositories, services) and the frontend follows component-based architecture.
- Modular Design: The presence of multiple packages/modules (CLI, config, controller, exception, logging, repository, service) in the backend indicates modularity. Similarly, the React structure is organized by components, pages, hooks, and services.
- External Dependencies: MongoDB integration (optional but recommended), use of Maven for backend builds, and Node.js/npm for frontend dependency management.

##### Specify the Technologies and Frameworks
- Backend: Java, Spring Boot, Maven, Logback, and MongoDB (for persistence). Also include specific classes responsible for vector database interactions and LLM calls.
- Frontend: React, TypeScript, Vite (for development server and build setup), Node.js, and npm.
- Utilities: Shell scripts (run-app.sh, start-backend.sh, start-frontend.sh) that orchestrate the startup process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (React/TypeScript)"
        UIComponents["UI Components"]:::frontend
        MainPages["Main Pages"]:::frontend
        APIService["API Communication Service"]:::frontend
        FrontConfig["Configuration Files"]:::frontend
        LogsViewer["Logs Viewer"]:::frontend
    end

    subgraph "Backend (Spring Boot)"
        subgraph "Web Service Layer"
            Controllers["Controller Layer"]:::backend
            Models["Model Layer"]:::backend
            ServiceLayer["Service Layer"]:::backend
            RepositoryLayer["Repository Layer"]:::backend
            ConfigLayer["Configuration Layer"]:::backend
            ExceptionHandling["Exception Handling"]:::backend
            subgraph "Backend Logging"
                LoggingJava["Logging (Java)"]:::backend
                LogbackConfig["Logback Config"]:::backend
                LogsFolder["Logs Directory"]:::backend
            end
        end
        subgraph "CLI Services"
            CLIServices["CLI Service Layer"]:::backend
        end
    end

    subgraph "Databases"
        MongoDB["MongoDB"]:::database
        VectorDB["Vector Database"]:::database
    end

    CLIUtilities["CLI Utilities"]:::cli

    subgraph "Feature Analysis Workflow"
        TextInput["Text Input"]:::workflow
        Ambiguity["Ambiguity Detection"]:::workflow
        QueryPreprocess["Query Preprocessing"]:::workflow
        VectorQuery["Vector DB Query"]:::workflow
        CodeChunk["Code Chunk Collection"]:::workflow
        LLMAnalysis["LLM Analysis"]:::workflow
        ComplexityReport["Complexity Report"]:::workflow
    end

    %% Connections between Frontend and Backend
    APIService -->|"REST_call"| Controllers
    Controllers -->|"Process_Request"| ServiceLayer
    ServiceLayer -->|"Data_Operations"| RepositoryLayer

    %% Feature Analysis Workflow executed by Service Layer
    ServiceLayer -->|"Executes"| TextInput
    TextInput -->|"Step1"| Ambiguity
    Ambiguity -->|"Step2"| QueryPreprocess
    QueryPreprocess -->|"Step3"| VectorQuery
    VectorQuery -->|"Step4"| CodeChunk
    CodeChunk -->|"Step5"| LLMAnalysis
    LLMAnalysis -->|"Step6"| ComplexityReport
    ComplexityReport -->|"Response"| MainPages

    %% Database interactions
    ServiceLayer -->|"Persist_Data"| MongoDB
    ServiceLayer -->|"Query_Data"| VectorDB

    %% CLI interactions
    CLIUtilities -->|"Triggers"| CLIServices
    CLIServices -->|"Invokes_Services"| ServiceLayer

    %% Logging flows
    Controllers -->|"Logs_Event"| LoggingJava
    ServiceLayer -->|"Logs_Event"| LoggingJava
    APIService -->|"Log_Request"| LogsViewer
    LogsViewer -->|"Fetches"| LogbackConfig

    %% Click Events for Backend Components
    click Controllers "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/controller"
    click Models "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/model"
    click ServiceLayer "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/service"
    click CLIServices "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/cli/service"
    click RepositoryLayer "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/repository"
    click ConfigLayer "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/config"
    click ExceptionHandling "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/exception"
    click LoggingJava "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/logging"
    click LogbackConfig "https://github.com/mynk322/flowpulse/blob/main/ContextCoach1/src/main/resources/logback-spring.xml"
    click LogsFolder "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/logs"

    %% Click Events for Frontend Components
    click UIComponents "https://github.com/mynk322/flowpulse/tree/main/feature-clarify-analyze1/src/components"
    click MainPages "https://github.com/mynk322/flowpulse/tree/main/feature-clarify-analyze1/src/pages"
    click APIService "https://github.com/mynk322/flowpulse/blob/main/feature-clarify-analyze1/src/services/api.ts"
    click FrontConfig "https://github.com/mynk322/flowpulse/tree/main/feature-clarify-analyze1/"
    click LogsViewer "https://github.com/mynk322/flowpulse/blob/main/feature-clarify-analyze1/src/components/logs-viewer.tsx"

    %% Click Events for Database Components
    click MongoDB "https://github.com/mynk322/flowpulse/blob/main/ContextCoach1/src/main/java/com/contextcoach/config/MongoConfig.java"
    click VectorDB "https://github.com/mynk322/flowpulse/tree/main/ContextCoach1/src/main/java/com/contextcoach/cli/service"

    %% Click Event for CLI Utilities
    click CLIUtilities "https://github.com/mynk322/flowpulse/blob/main/ContextCoach1/cli/feature-complexity-cli.sh"

    %% Styles
    classDef frontend fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef backend fill:#c2d1f0,stroke:#333,stroke-width:2px;
    classDef database fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef cli fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef workflow fill:#ffdab9,stroke:#333,stroke-width:2px;
```
