memory-bank-large-repos-part1.md

Objective: To collaboratively create and establish rules for a comprehensive, modular, and maintainable "memory bank" for a large software project. This memory bank will serve as the primary source of structured, persistent context for AI assistants (like yourself) working on this project, ensuring consistent understanding, efficient navigation, effective collaboration, and clear visual explanations where needed.

Phase 0: Prerequisites and Assumptions

Goal: To ensure all necessary conditions and understandings are in place before commencing the memory bank creation process.

Prerequisites for You (AI Assistant):

• You have read-only access to the project's entire codebase (all relevant repositories, modules, and services). If not, I will provide comprehensive descriptions.
• You have the capability to understand and analyze code structure, dependencies, and common programming patterns across various languages and frameworks relevant to this project.
• You can create directories and Markdown (.md) files within a specified project path, or provide me with the exact structure and content to create them.
• You can generate and understand Mermaid syntax for diagrams to be embedded directly within Markdown files.

Assumptions:

• The human user (me) will provide necessary clarifications, information, and approvals at each stage.
• The memory-bank/ directory will be version-controlled (e.g., using Git) alongside the project's codebase by the human team.
• This process is iterative, and we may revisit earlier phases based on discoveries in later phases.

Completion Criteria for Phase 0:

• You confirm understanding of these prerequisites and assumptions.
• You acknowledge readiness to proceed to Phase 1.

(AI, please confirm the above before we proceed.)

---

Phase 1: Project Analysis & Interactive Understanding

Goal: To gain a deep and shared understanding of the project's structure, components, technology stack, and operational context, including identifying needs for visual explanations.

1. Initial Automated Analysis (If Code Access Granted):

   • Perform an initial automated scan of the codebase to identify:
   • Overall directory structure and key top-level folders.
   • Potential primary modules, microservices, shared libraries, or distinct functional components.
   • Predominant programming languages, frameworks, and build tools.
   • Any existing documentation (e.g., READMEs, docs/ folders, wikis, ADRs) or configuration files (e.g., docker-compose.yml, package.json) that might hint at architecture or project standards.
   • Summarize your initial findings briefly for my review.

2. Clarifying Questions (Crucial - Ask me these before proceeding to structure proposal): To ensure the memory bank is effective and accurately reflects the project, please ask me clarifying questions. Your questions should aim to fill any gaps from your initial analysis and help you understand:

   • Project Purpose & Domain: What is the primary business goal of this project? What specific problem does it solve, and for whom? What is the core domain?
   • Technology Stack (Confirmation & Detail): Confirm the main programming languages, frameworks, databases, and significant libraries/SDKs used across the project and within its key modules/services.
   • Project Structure (Confirmation & Detail): Is this a monorepo? If so, how are distinct projects/services/modules typically demarcated? If multi-repo, how are they related and managed?
   • Key Modules/Services (Identification & Confirmation): Based on your analysis and my input, let's list and confirm the primary modules, microservices, shared libraries, or distinct functional components. What is the single most critical responsibility of each?
   • Inter-Component Interaction & Data Flow: How do these different modules/services communicate (e.g., REST APIs, gRPC, message queues, shared databases, internal SDKs, event-driven patterns)? When describing these interactions, could an embedded Mermaid diagram (e.g., sequence or activity diagram) significantly help clarify this?
   • Architectural Style & Key Patterns: What is the dominant architectural style (e.g., microservices, layered monolith, event-driven, SOA)? Are there existing architectural diagrams (e.g., C4, component, sequence, deployment) that are critical to understanding the project? If so, can you point me to them so we can ensure their essence is captured as embedded Mermaid diagrams in the memory bank?
   • Critical Business Logic: Which modules/services contain the most critical, complex, or unique business logic that needs careful documentation? Would embedded flowcharts or activity diagrams (using Mermaid) be beneficial here?
   • Development & Deployment Lifecycle: Briefly, what are the key stages in the development lifecycle (e.g., local environment setup, testing strategies/frameworks, CI/CD pipelines and tools, deployment environments, release cadence)? Could a simple pipeline diagram, embedded using Mermaid, be useful?
   • Existing Knowledge & Key Contacts/Teams: Is there any existing high-level documentation, ADRs, or key individuals/teams responsible for specific components that I should be aware of or consult?
   • Areas of High Churn or Complexity: Are there any parts of the project that are particularly complex, frequently changing, historically prone to issues, or have significant technical debt?
   • Audience for Memory Bank: Who is the primary audience for this memory bank (e.g., AI assistants like you, new human developers, current team members for cross-functional understanding, operations teams)? This will influence the level of detail, tone, and the prioritization of embedded diagrams.
   • Security & Compliance Considerations: Are there any overarching security considerations or compliance requirements that need careful documentation, potentially with embedded diagrams illustrating trust boundaries or data flows relevant to compliance?

(Wait for my answers to your questions. Feel free to ask follow-up questions to ensure complete clarity before proposing the memory bank structure.)

Completion Criteria for Phase 1:

• You have performed an initial analysis of the project structure (if access was provided) or have received my initial overview.
• You have asked comprehensive clarifying questions, including those about the potential need for embedded diagrams.
• I have provided answers to your questions, and you have confirmed understanding.
• You state that you have a sufficient high-level understanding to propose a detailed memory bank structure, including initial thoughts on where embedded diagrams will be vital.

(AI, once you believe Phase 1 is complete, please confirm and state your readiness to proceed to Phase 2.)

---

Phase 2: Proposing and Creating the Memory Bank Structure

Goal: To define and create a logical, hierarchical directory and file structure for the memory bank that accurately reflects the project's organization, facilitates easy navigation and maintenance, and exclusively uses diagrams embedded directly within Markdown files.

1. Propose Structure:

   • Based on your analysis and our discussion in Phase 1, propose a detailed directory structure for the memory-bank/.
   • Illustrative Structure Diagram (Example to guide your proposal, showing only Markdown files and directories as all diagrams are embedded):

     graph TD
       A[memory-bank/] --> B[00-project-global-overview.md];
       A --> C[01-global-architecture.md];
       A --> D[CONTRIBUTING_GUIDELINES.md];
       A --> E[INDEX.md];
       A --> H[services/];
       H --> I[authentication-service/];
       I --> J[00-overview.md];
       I --> K[01-architecture-and-design.md];
       A --> L[modules/];
       L --> M[reporting-module/];
       M --> N[00-overview.md];
     

     Loading
   • Your proposal should include:
   • A root memory-bank/ directory.
   • A set of global project context files at the root.
   • Logically grouped subdirectories for each major component (e.g., services/, modules/, libraries/).
   • For each proposed subdirectory and root file, list the initial set of Markdown files (e.g., 00-overview.md). For each key .md file (especially architecture, overview, and process files), explicitly note if you anticipate an embedded diagram (using Mermaid) would be highly beneficial for human and AI understanding, and suggest the type of diagram (e.g., component diagram for an architecture file, sequence diagram for an API interaction, flowchart for a process).

2. Review and Approval:

   • I will review your proposed structure and your suggestions for initial embedded Mermaid diagram needs. We may iterate on this.

3. Create Structure (Upon Approval):

   • Once approved, create the memory-bank/ directory and all subdirectories.
   • Create all approved placeholder .md files. Each file MUST begin with `last-updated:

---

Phase 3: Defining Content Structure, Guidelines, and Examples

Goal: To establish clear templates, best practices for content creation (exclusively using embedded Mermaid diagrams), and illustrative examples.

1. Propose Content Outlines/Templates:

   • For each type of .md file, propose a detailed template or outline. Your proposed outlines should explicitly include ## Suggested Embedded Diagrams sections where appropriate, listing the types of Mermaid diagrams (e.g., component, sequence, flowchart, ERD) that would enhance understanding for that specific document and guide the content creator. Emphasize the use of Mermaid syntax for all diagrams.

2. Draft memory-bank/CONTRIBUTING_GUIDELINES.md: Enhance this draft to include:

   • ... (all previous guideline points: Purpose, Clarity, Actionable Info, AI-Consumable, Relative Links, File Size, last-updated, Cross-Reference Tags, Tone)
   • Diagrams Best Practices (New/Enhanced Section):
     • "Use Diagrams Actively: Diagrams are strongly encouraged to explain complex systems, flows, and structures. They significantly aid both human and AI comprehension."
     • "Embedded Mermaid Diagrams (Exclusive Method): All diagrams (sequence, flowchart, class, component, state, ERD, Gantt charts, etc.) MUST be created using Mermaid.js syntax directly within your Markdown files. This keeps diagrams version-controlled with the documentation and easily editable as text. No external diagram image files are to be used."
       • Example Mermaid code block to include in the guidelines:

         ```mermaid
         graph TD
             A[Start] --> B{Decision?};
             B -- Yes --> C[Action 1];
             B -- No  --> D[Action 2];
             C --> E[End];
             D --> E;

         (This will render as a simple flowchart when viewed in a Markdown previewer that supports Mermaid.)

     • "Clarity and Simplicity: Ensure embedded Mermaid diagrams are clear, well-annotated, and directly relevant to the content. Avoid overly cluttered diagrams; split complex ideas into multiple simpler diagrams if necessary."
     • "Accessibility: For complex embedded Mermaid diagrams, provide a brief textual summary of the diagram's purpose and key takeaways immediately following or preceding the diagram to aid understanding for all users and tools."

3. Provide Examples of "Good" vs. "Bad" Memory Bank Entries (Ensure "Good" examples make excellent use of embedded Mermaid diagrams):

   • (Use the same examples as before, but ensure Example 2: Architectural Decision explicitly uses a well-formatted embedded Mermaid diagram, and perhaps add a new example showcasing a different embedded Mermaid diagram type like a component diagram.)

4. Review and Approval:

   • I will review the proposed templates (with their embedded Mermaid diagram suggestions), the enhanced CONTRIBUTING_GUIDELINES.md, and the examples.

Completion Criteria for Phase 3:

• Templates/outlines for memory bank files, exclusively prompting for embedded Mermaid diagram inclusion, are approved.
• CONTRIBUTING_GUIDELINES.md, with robust guidance on creating and using only embedded Mermaid diagrams, is approved.
• Examples of "good" vs. "bad" entries, effectively demonstrating embedded Mermaid diagram usage, are approved.

(AI, once these are approved, please confirm readiness for Phase 4.)