# SOLID Design Principles - Coding Assistant Guidelines

When generating, reviewing, or modifying code, follow these guidelines to ensure adherence to SOLID principles:

## 1. Single Responsibility Principle (SRP)

- Each class must have only one reason to change.
- Limit class scope to a single functional area or abstraction level.
- When a class exceeds 100-150 lines, consider if it has multiple responsibilities.
- Separate cross-cutting concerns (logging, validation, error handling) from business logic.
- Create dedicated classes for distinct operations like data access, business rules, and UI.
- Method names should clearly indicate their singular purpose.
- If a method description requires "and" or "or", it likely violates SRP.
- Prioritize composition over inheritance when combining behaviors.

## 2. Open/Closed Principle (OCP)

- Design classes to be extended without modification.
- Use abstract classes and interfaces to define stable contracts.
- Implement extension points for anticipated variations.
- Favor strategy patterns over conditional logic.
- Use configuration and dependency injection to support behavior changes.
- Avoid switch/if-else chains based on type checking.
- Provide hooks for customization in frameworks and libraries.
- Design with polymorphism as the primary mechanism for extending functionality.

## 3. Liskov Substitution Principle (LSP)

- Ensure derived classes are fully substitutable for their base classes.
- Maintain all invariants of the base class in derived classes.
- Never throw exceptions from methods that don't specify them in base classes.
- Don't strengthen preconditions in subclasses.
- Don't weaken postconditions in subclasses.
- Never override methods with implementations that do nothing or throw exceptions.
- Avoid type checking or downcasting, which may indicate LSP violations.
- Prefer composition over inheritance when complete substitutability can't be achieved.

## 4. Interface Segregation Principle (ISP)

- Create focused, minimal interfaces with cohesive methods.
- Split large interfaces into smaller, more specific ones.
- Design interfaces around client needs, not implementation convenience.
- Avoid "fat" interfaces that force clients to depend on methods they don't use.
- Use role interfaces that represent behaviors rather than object types.
- Implement multiple small interfaces rather than a single general-purpose one.
- Consider interface composition to build up complex behaviors.
- Remove any methods from interfaces that are only used by a subset of implementing classes.

## 5. Dependency Inversion Principle (DIP)

- High-level modules should depend on abstractions, not details.
- Make all dependencies explicit, ideally through constructor parameters.
- Use dependency injection to provide implementations.
- Program to interfaces, not concrete classes.
- Place abstractions in a separate package/namespace from implementations.
- Avoid direct instantiation of service classes with 'new' in business logic.
- Create abstraction boundaries at architectural layer transitions.
- Define interfaces owned by the client, not the implementation.

## Implementation Guidelines

- When starting a new class, explicitly identify its single responsibility.
- Document extension points and expected subclassing behavior.
- Write interface contracts with clear expectations and invariants.
- Question any class that depends on many concrete implementations.
- Use factories, dependency injection, or service locators to manage dependencies.
- Review inheritance hierarchies to ensure LSP compliance.
- Regularly refactor toward SOLID, especially when extending functionality.
- Use design patterns (Strategy, Decorator, Factory, Observer, etc.) to facilitate SOLID adherence.

## Warning Signs

- God classes that do "everything"
- Methods with boolean parameters that radically change behavior
- Deep inheritance hierarchies
- Classes that need to know about implementation details of their dependencies
- Circular dependencies between modules
- High coupling between unrelated components
- Classes that grow rapidly in size with new features
- Methods with many parameters

Create a Mermaid `flowchart TD` diagram visualizing the functional structure and call flow of the current software project.  

**Diagram Content:**

*  **Structure:** Use subgraphs to represent files or modules containing functions/methods from the primary source code directories (e.g., `src/`, `app/`, exclude tests, dependencies).

*  **Functions:** Represent key functions/methods within their respective subgraphs as nodes (labeled `FileName.functionName` or `ClassName.methodName`).

*  **Function Purpose:** For each function node, provide a concise description. *Prioritize* extracting this from existing code comments (docstrings, JSDoc). If comments are absent, *attempt* to infer the purpose based on name and code, clearly marking it as inferred (e.g., "[inferred] Does X").  Display the function purpose as a tooltip associated with the node rather than directly in the node label to maintain visual clarity.

*  **Call Relationships:** Draw directed arrows between function nodes to indicate direct calls made *within* the analyzed project source code.

**Analysis & Highlighting:**

*  **Unused Functions:** Clearly identify and visually distinguish function nodes that are not called by any other analyzed function (potential dead code).

*  **Similar Functionality:** *Attempt* to identify functions that appear to perform highly similar tasks, even if not syntactically identical. Highlight these nodes distinctly and potentially add a note about suspected similarity.

*  **Highlighting** Use Mermaid classDef statements to define distinct styles (e.g., different border color/stroke, fill color) for 'unused' and 'similar' function nodes, and apply these classes to the relevant nodes in the diagram.

**Scope**

*   Focus analysis on primary source code, explicitly excluding test suites, configuration files, and third-party libraries unless instructed otherwise.

*   Exclude any files excluded by .gitignore

**Output:**

*   Use Github flavored markdown.

*   Document has the following layout:
    *   A mermaid graph of the call graph.
    *  A table listing all functions with a brief summary of their purpose.
    *  A table listing dead code (unused functions).
    *  A table listing similar functions.


*   Save it as `docs/CALLGRAPH.md`.    

**Process:**

Follow this step by step process:

1.  Start by creating a list of all appropriate source files.  If a file tree wasn't provided in the prompt create one first.

2.  For each file, parse out function definitions and their direct calls.

3.  Build the graph structure.

4.  For each function analyze it's purpose and add a summary to each function on the graph.

5.  Analyze for unused functions and similar functionality.

6.  Generate the markdown output.
        a. Generate mermaid graph
        b. Generate list of functions with their purposes in markdown table
        c. List dead code in markdown table
        d. List similar functions in markdown table