Supercharge Laravel development with AI

---
description:
globs:
alwaysApply: true
---
# Architecture Documentation: tts.test SaaS Platform
 
## 1. High-Level Overview
 
### System Purpose and Functionalities
 
The system is a Software as a Service (SaaS) platform designed primarily for **Spanish Text-to-Speech (TTS) synthesis**. Based on the codebase structure (`Project`, `ProjectAudioGeneration` models, TTS service integration), its core functionalities include:
 
- **User Authentication & Management:** User registration, login, password management, profile updates, and email verification.
- **Team Management:** Users belong to teams, can own teams, and have a concept of a "current team" for context switching.
- **Project Management:** Users can create projects within their current team to organize TTS tasks.
- **Text-to-Speech (TTS) Generation:** Users can input text (via a rich text editor - Tiptap), select a voice, and initiate an asynchronous job to generate an audio file using an external TTS service (Google Cloud TTS).
- **Audio Management:** Generated audio files are stored (using Spatie MediaLibrary) and associated with their respective generation tasks and projects. Users can preview/play generated audio within the application.
- **Settings:** Users can manage profile details, passwords, and interface appearance (light/dark/system themes).
 
### Architectural Style
 
The system follows a **monolithic, client-server architecture**.
 
- The backend is a traditional **Laravel (PHP)** application adhering largely to the **Model-View-Controller (MVC)** pattern, extended with **Action classes** to encapsulate specific business logic.
- The frontend is a **React (TypeScript) Single Page Application (SPA)**.
- **Inertia.js** acts as the bridge between the Laravel backend and the React frontend, allowing the backend controllers to directly render React page components and pass data without requiring a separate REST/GraphQL API.
- **Asynchronous processing** is used for time-consuming tasks like TTS generation via Laravel Queues and Jobs.
 
### Core Technologies, Languages, and Libraries
 
- **Backend:**
    - Language: PHP 8.4+
    - Framework: Laravel 12.x
    - ORM: Eloquent
    - Queue System: Laravel Queues (Configured for Database driver by default)
    - Database: PostgreSQL (Migrations set up, default connection often SQLite for local dev via `.env.example`)
    - Key Libraries:
        - `inertiajs/inertia-laravel`: Bridge to Inertia frontend.
        - `tightenco/ziggy`: Share Laravel routes with JavaScript.
        - `spatie/laravel-data`: Data Transfer Objects (DTOs).
        - `spatie/laravel-medialibrary`: File/Media management.
        - `google/cloud-text-to-speech`: Google Cloud TTS client library.
- **Frontend:**
    - Language: TypeScript
    - Framework/Library: React 19.x
    - UI Components: shadcn/ui (built on Radix UI and Tailwind CSS)
    - State Management: Primarily via Inertia props; component-level state managed by React hooks.
    - Routing: Inertia.js (client-side), Laravel (server-side definition).
    - Build Tool: Vite
    - Styling: Tailwind CSS v4
    - Rich Text Editor: Tiptap
- **External Services:**
    - Google Cloud Text-to-Speech API
 
## 2. Component Interactions
 
### Major Components
 
- **Frontend (React/Inertia - `resources/js`)**:
    - `pages/`: Contains React components representing individual application pages (e.g., `dashboard.tsx`, `Project.tsx`, `settings/profile.tsx`). Rendered by Inertia based on backend responses.
    - `layouts/`: Structural components defining page layouts (e.g., `AppSidebarLayout`, `AuthSimpleLayout`, `SettingsLayout`).
    - `components/`: Reusable UI elements (`ui/` - shadcn/ui primitives, `app-logo.tsx`, `TiptapEditor.tsx`, `AudioPlayer.tsx`, etc.).
    - `hooks/`: Custom React hooks (e.g., `useAppearance`, `useMobile`).
    - `lib/`: Utility functions (e.g., `utils.ts`).
- **Backend (Laravel - `app/`)**:
    - `Http/Controllers/`: Handle incoming HTTP requests, interact with Actions/Models, and return Inertia responses (e.g., `DashboardController`, `ProjectController`, `Auth/RegisteredUserController`, `Settings/ProfileController`).
    - `Http/Requests/`: Define validation rules and authorization logic for specific requests (e.g., `StoreProjectRequest`, `StoreProjectAudioGenerationRequest`). Often create DTOs.
    - `Http/Middleware/`: Process requests before they reach controllers (e.g., `HandleInertiaRequests` shares data, `HandleAppearance` manages theme cookies).
    - `Http/Resources/`: Transform Eloquent models into structured data for the frontend (e.g., `ProjectResource`, `UserResource`, `ProjectAudioGenerationResource`).
    - `Actions/`: Encapsulate specific business logic operations (e.g., `CreateProjectAction`, `StartAudioGenerationAction`, `GetDashboardData`). Called by Controllers.
    - `Models/`: Eloquent models representing database tables and relationships (`User`, `Team`, `Project`, `Voice`, `ProjectAudioGeneration`). Interact with the database.
    - `Jobs/`: Define asynchronous tasks processed by the queue (`GenerateSpeechJob`).
    - `Services/`: Wrapper classes for external services (`TextToSpeechService`).
    - `Providers/`: Service providers for bootstrapping services (`TextToSpeechServiceProvider`).
    - `Policies/`: Define authorization rules for model actions (`ProjectPolicy`, `ProjectAudioGenerationPolicy`).
    - `Enums/`: Define enumerated types (`AudioGenerationStatus`).
    - `Exceptions/`: Custom exception classes (`TextToSpeechGenerationException`).
- **Database (`database/`)**: Stores application state (users, teams, projects, voices, audio generations, media files, jobs, cache, sessions). Accessed via Eloquent Models. Migrations define the schema.
- **Queue System (`config/queue.php`, `app/Jobs/`)**: Manages background tasks. `GenerateSpeechJob` is pushed onto the queue and processed by a worker.
- **File Storage (`config/filesystems.php`, `storage/`)**: Stores generated audio files (via Spatie MediaLibrary, configured for local or cloud disks like `teams_cloud`).
- **External TTS Service (Google Cloud)**: Integrated via `TextToSpeechService` for audio synthesis.
 
### Interaction Patterns
 
- **Client-Server (Inertia)**: User interacts with the React frontend. Actions trigger Inertia visits/requests to the Laravel backend. Laravel Controllers handle these, often using Actions, Models, and Requests, then return an Inertia Response with a page component and data (transformed by Resources).
- **Controller-Action**: Controllers delegate complex business logic to dedicated Action classes (e.g., `ProjectController` uses `CreateProjectAction`).
- **Action-Model/DB**: Actions interact with Eloquent Models to read/write data from the database.
- **Request-Validation**: Form Requests automatically validate incoming data before controller/action logic executes.
- **Job Dispatch**: Controllers or Actions dispatch Jobs (e.g., `StartAudioGenerationAction` dispatches `GenerateSpeechJob`) to the queue for asynchronous processing.
- **Job-Service**: Jobs utilize Services to interact with external APIs (e.g., `GenerateSpeechJob` uses `TextToSpeechService`).
- **Service-External API**: Services make calls to external APIs (e.g., `TextToSpeechService` calls Google Cloud TTS).
- **Model-Media Library**: Models implementing `HasMedia` (e.g., `ProjectAudioGeneration`) interact with Spatie MediaLibrary to manage associated files.
- **Middleware Pipeline**: Requests pass through middleware for authentication, Inertia setup, etc.
 
### Mermaid Component Diagram
 
```mermaid
graph LR
    subgraph "User Browser"
        Frontend["React SPA (Inertia.js)"]
    end
 
    subgraph "Laravel Backend"
        Middleware["Middleware Pipeline"]
        Controllers["Controllers"]
        Actions["Action Classes"]
        FormRequests["Form Requests"]
        Models["Eloquent Models"]
        QueueSystem["Queue"]
        Jobs["Jobs (e.g., GenerateSpeechJob)"]
        Services["Services (e.g., TextToSpeechService)"]
        MediaLib["Media Library (Spatie)"]
        Policies["Policies"]
        Resources["API Resources"]
 
        Middleware -- Request --> Controllers
        Controllers -- Uses --> Actions
        Controllers -- Uses --> FormRequests
        Controllers -- Returns Inertia Response --> Frontend
        Actions -- Uses --> Models
        Actions -- Dispatches --> QueueSystem
        Jobs -- Processed by --> QueueWorker
        Jobs -- Uses --> Services
        Jobs -- Uses --> Models
        Models -- Interacts with --> Database[(Database)]
        Models -- Uses --> MediaLib
        MediaLib -- Writes/Reads --> FileStorage[(File Storage)]
        Services -- Calls --> ExternalTTS["External TTS API (Google)"]
        Policies -- Authorizes --> Controllers
        FormRequests -- Validates --> Controllers
        Resources -- Formats Data --> Controllers
    end
 
    subgraph "Infrastructure"
        QueueWorker["Queue Worker"]
        Database[(Database)]
        FileStorage[(File Storage)]
    end
 
    subgraph "External Services"
        ExternalTTS
    end
 
    Frontend -- HTTP Request --> Middleware
```
 
## 3. Data Flow Diagrams
 
### Audio Generation
 
```mermaid
graph LR
    subgraph "User Interaction - React Project Page"
        A[User Edits Text] --> B(TiptapEditor);
        C[User Selects Voice] --> D(Voice Select Dropdown);
        E[User Clicks Generate] -- Form Submit (Text JSON, Voice ID) --> F["POST /projects/ID/generations"];
    end
 
    subgraph "Backend Processing"
        F -- Request --> G["StoreProjectAudioGenerationRequest"];
        G -- Validates Text/Voice, Checks for In-Progress, Authorizes --> G;
        G -- Creates DTO --> H[StartAudioGenerationData DTO];
        F -- Passes DTO --> I["ProjectAudioGenerationController store"];
        I -- Calls Action --> J["StartAudioGenerationAction handle"];
        J -- Creates Generation Record (Status: PENDING) --> K[(Database - project_audio_generations)];
        J -- Dispatches Job --> L{Queue::dispatch};
        I -- Redirects Back --> M["React Project Page (w/ Flash Message)"];
    end
 
    subgraph "Async Job Processing"
        N[Queue Worker] -- Picks Up Job --> O["GenerateSpeechJob handle"];
        O -- Finds Generation & Voice --> P[(Database - project_audio_generations, voices)];
        O -- Checks Voice Active --> O;
        O -- Gets Plain Text --> O;
        O -- Calls Service --> Q["TextToSpeechService synthesizeAndSave"];
        Q -- Calls External API --> R[Google Cloud TTS API];
        R -- Returns Audio Content --> Q;
        Q -- Saves Audio to Disk --> S[(File Storage - teams_cloud/local)];
        O -- Adds Media Record --> T[Spatie MediaLibrary];
        T -- Creates Media Entry --> U[(Database - media)];
        O -- Updates Generation Status (COMPLETED/FAILED) --> K;
    end
 
    style K fill:#f9f,stroke:#333,stroke-width:2px
    style P fill:#f9f,stroke:#333,stroke-width:2px
    style U fill:#f9f,stroke:#333,stroke-width:2px
    style S fill:#ccf,stroke:#333,stroke-width:2px
```
 
## 4. Design Decisions and Rationale
 
- **Laravel Framework:** Chosen likely for its rapid development capabilities, extensive ecosystem (authentication, ORM, queues, testing), and strong community support. Its MVC structure provides a standard organization.
- **Inertia.js with React:** Selected to build a modern SPA-like frontend without the complexity of managing a separate API backend. Allows Laravel controllers to directly serve React components, simplifying data flow.
- **TypeScript:** Used in the frontend for enhanced type safety, improved developer experience, and better code maintainability compared to plain JavaScript, especially in larger applications.
- **Shadcn/UI & Tailwind CSS:** Leveraged for the frontend UI. Provides unstyled, accessible component primitives built with Radix UI, styled using Tailwind CSS utility classes. This offers high customizability and consistency while speeding up UI development. Rationale: modern, utility-first CSS, component reuse.
- **Action Classes (`app/Actions`)**: Used to separate business logic from controllers. This promotes cleaner controllers, improves code organization, and makes the core logic more testable and reusable. Rationale: Single Responsibility Principle, maintainability.
- **Data Transfer Objects (DTOs - `spatie/laravel-data`)**: Used in `StartAudioGenerationData` and `ProjectData` (within `StoreProjectRequest`). Ensures structured, type-safe data transfer between layers (Request -> Action). Rationale: Improves code clarity and reduces errors from passing unstructured arrays.
- **Eloquent ORM:** Laravel's default ORM is used for database interaction. Rationale: Convention, ease of use, integrates well with Laravel features.
- **ULIDs for Primary Keys:** Modern choice over traditional auto-incrementing integers. ULIDs are sortable, unique across tables/systems, and less predictable. Rationale: Scalability, uniqueness.
- **Queues & Jobs (`app/Jobs`)**: TTS generation is offloaded to a background job (`GenerateSpeechJob`). Rationale: Prevents blocking HTTP requests for long-running tasks, improves user experience, allows for retries and scaling of workers.
- **Service Layer (`app/Services`)**: A dedicated `TextToSpeechService` encapsulates interaction with the Google Cloud TTS API. Rationale: Decouples external service interaction, makes it easier to test or swap implementations.
- **Service Provider (`app/Providers`)**: `TextToSpeechServiceProvider` handles the instantiation and dependency injection of the `TextToSpeechClient`. Rationale: Centralized service configuration, follows Laravel's IoC principles.
- **Spatie MediaLibrary (`spatie/laravel-medialibrary`)**: Used for handling the storage and association of generated audio files (`ProjectAudioGeneration` model). Rationale: Provides a robust and conventional way to manage file uploads and associations in Laravel.
- **API Resources (`app/Http/Resources`)**: Used to transform Eloquent models into consistent JSON structures for the Inertia frontend. Rationale: Controls data exposure, ensures consistent data format, decouples frontend from raw model structure.
- **Policies (`app/Policies`)**: Used for authorization logic (e.g., ensuring a user can only view/modify projects or cancel generations belonging to their team). Rationale: Centralizes authorization rules, keeps controllers cleaner.
- **Pest Testing Framework:** Used for writing tests. Rationale: Modern PHP testing framework with a focus on readability and developer experience.
 
## 5. System Constraints and Limitations
 
- **External Dependency (Google Cloud TTS):**
    - Requires valid Google Cloud credentials (`GOOGLE_APPLICATION_CREDENTIALS`) and a configured Project ID (`GOOGLE_CLOUD_PROJECT`).
    - Subject to Google Cloud pricing, usage limits, and potential API changes.
    - Network connectivity to Google Cloud APIs is essential for TTS functionality.
- **Asynchronous Processing:**
    - Requires a running queue worker (`php artisan queue:work` or similar) to process `GenerateSpeechJob`. Without it, audio generation will remain pending.
    - Queue configuration (`config/queue.php`) determines reliability and throughput (e.g., database driver might not be ideal for high load vs. Redis/SQS).
- **File Storage:**
    - Requires correctly configured filesystem disks (`config/filesystems.php`), especially the `teams_cloud` disk if using cloud storage (like S3 or DO Spaces). Credentials and bucket names must be set in `.env`.
    - Storage costs apply if using cloud storage.
    - Local storage (`public` disk linked via `storage:link`) might not be suitable for production scaling or multi-server deployments.
- **Inertia SSR:**
    - The configuration (`config/inertia.php`) enables Server-Side Rendering. This requires Node.js on the server and a running SSR process (`php artisan inertia:start-ssr`) for optimal initial page loads. If SSR is not running or fails, Inertia falls back to client-side rendering.
- **Environment Configuration:** The application relies heavily on environment variables defined in `.env` (based on `.env.example`) for database connections, API keys, URLs, etc. Incorrect configuration will lead to failures.
- **Scalability:**
    - TTS generation can be a bottleneck. Scaling requires adding more queue workers.
    - Database performance under load depends on the chosen database and server resources.
    - Filesystem performance depends on the chosen disk driver and infrastructure.
- **Error Handling:** While the `GenerateSpeechJob` includes basic failure handling (updating status to FAILED), more sophisticated error reporting or user notification mechanisms might be needed for production. The `TextToSpeechGenerationException` provides a specific exception type.
- **Security:** Assumes standard Laravel security practices are followed. Sensitive credentials (like Google Cloud keys) must be securely managed and not committed to version control. Media URLs generated for cloud storage are temporary and time-limited.

---
description: Laravel project rules
globs: *.php
alwaysApply: false
---
# Laravel project rules
- Every time you have to run an php artisan command, run it with "herd" at the start. Example: `herd php artisan migrate`.
 
## Models
- Always create models using the artisan command.
- All models use ULIDs instead of big integers for ids as primary key.
- All models should be soft deleted.
 
## Controllers
- Always create controllers using the artisan command.
- Create controllers following laravel conventions, having index, create, store, show, edit, update, delete method. But only add the methods you need for the specific case.
- When storing or updating, always use form requests for data validation.
- Don't just put all the logic in the controller, use action classes to clearly separate logic.
- Whenever you have to return data to inertiajs or as json, use api resources, and only share the data you need to share.
- Always create feature tests for the controller, mocking the external services.
- Test all the form request validation rules by testing the full request lifecycle, and asserting you got the correct error.
 
## Form Requests
- Always create form requests using the artisan command.
 
## API Resources
- Always create api resources using the artisan command.
- When it makes sense, try to add a `dto` method that returns a data object from the request.
 
## Action classes
- These are simple classes that do only one specific action.
- Put all the action classes under app/Actions directory.
- Use a public `handle` method to execute the action.
- Pass all the necessary parameters to the `handle` method.
- Instead of passing raw arrays use data objects to pass the necessary data to the action class. We use Spatie laravel data package.
- Create feature test for all the action classes that you create.
 
## Testing
- We use Pest for testing. So, create tests following Pest conventions.
- Everytime you do changes to any php file, you have to run tests to verify everything works as expected.
- Always run mutation tests to verify that the code is fully covered.
- You can run tests with `herd php artisan test --filter=...`.
- You can run mutation tests with the next command `herd coverage ./vendor/bin/pest --mutate`.
- Never use `uses(RefreshDatabase::class)` because it's already added on [Pest.php](mdc:tests/Pest.php) file.
 
## Formatting
- Make sure you run "./vendor/bin/pint" command, without herd prefix, after you do any change to php files.

---
description: Use this rules whenever you are working on Laravel tests
globs:
alwaysApply: false
---
 
# General Guidelines
- Always use factory relation helpers to create models with relations.
**Example:**
     **DO:** `Team::factory()->for($user, 'owner')->create();` or `Project::factory()->for($team)->create();`
     **DON'T:** `Team::factory()->create(['owner_id' => $user->id]);

{
    "output": {
      "filePath": ".repomix/output/plan.xml",
      "style": "xml",
      "parsableStyle": true,
      "compress": false,
      "headerText": "Custom header text",
      "instructionFilePath": ".repomix/instructions/plan.md",
      "fileSummary": true,
      "directoryStructure": true,
      "removeComments": false,
      "removeEmptyLines": false,
      "topFilesLength": 5,
      "showLineNumbers": false,
      "copyToClipboard": false,
      "includeEmptyDirectories": false,
      "git": {
        "sortByChanges": true,
        "sortByChangesMaxCommits": 100
      }
    },
    "include": ["**/*"],
    "ignore": {
      "useGitignore": true,
      "useDefaultPatterns": true,
      "customPatterns": ["./repomix/**", "tmp/", "*.log", "storage/**", ".github/**", "artisan", "bootstrap/cache/**"]
    },
    "security": {
      "enableSecurityCheck": true
    }
  }

# Feature Implementation Planning
 
## Role
 
You are an AI assistant specializing in code analysis and software feature planning.
 
## Context
 
You will be provided with two main inputs:
 
1.  The **complete source code** of a software project.
2.  A **specific task** detailing a new feature to be added or an existing feature to be modified (provided below).
 
## Objective
 
Your primary objective is to analyze the provided code and the specific task, and then generate a detailed, step-by-step plan to implement the required changes. You **must** use the provided code as the primary context for all suggestions.
 
## Output Requirements
 
Your generated plan **must** include the following sections, clearly delineated:
 
1.  **Data Structure Definition:**
 
    - Analyze if the task necessitates the creation of new data structures (e.g., classes, interfaces, structs, database table schemas, configuration objects) or modifications to existing ones.
    - If new structures or modifications are needed, clearly define them. Include field names, data types, relationships, and any relevant constraints or default values. Use appropriate code-like notation for clarity (e.g., class definition syntax for the project's language). If no changes are needed, state this explicitly.
 
2.  **Implementation Steps:**
 
    - Provide a numbered list of specific, actionable steps required to implement the feature or modification.
    - **1. Prepare Git Branch:**
        - Instruct the user to check their current Git branch (e.g., using `git branch` or `git status`).
        - Instruct the user that if they are not already on a dedicated feature branch for this task (e.g., they are on `main`, `master`, or `develop`), they **must** create and check out a new feature branch before proceeding. Provide an example command with a placeholder name (e.g., `git checkout -b feature/your-feature-name`).
        - Emphasize that all subsequent code changes described in the plan should be committed to this new feature branch.
    - **2. [Original Step 1 - e.g., Modify File X]:** (Renumbered) Describe the next logical step...
    - **3. [Original Step 2 - e.g., Create File Y]:** (Renumbered) Describe the next logical step...
    - _(Continue renumbering and detailing all subsequent implementation steps)_
 
3.  **Code Snippets:**
 
    - For key steps involving code additions or significant modifications, provide relevant code snippets.
    - These snippets should illustrate **exactly** what needs to be added or changed. Use placeholders (e.g., `// ... existing code ...` or `/* TODO: Implement complex logic here */`) where appropriate, but provide the essential structure and key lines of code.
    - Ensure the snippets adhere to the coding style, conventions, and language/frameworks evident in the provided source code.
 
4.  **Unit Tests:**
 
    - Provide specific unit tests required to verify the correctness of the implemented changes.
    - These tests should cover:
        - Happy paths (expected successful execution).
        - Edge cases.
        - Potential error conditions or invalid inputs.
    - Write the tests using the testing framework and conventions already established in the project's source code. Include necessary imports, setup, assertions, and teardown.
 
5.  **Verification Instruction:**
 
    - Explicitly instruct the user to run the newly created unit tests _and_ the existing test suite (after committing changes to the feature branch) to ensure the changes work as expected and have not introduced regressions. Specify the command(s) if discernible from the project structure or common practices for the language/framework.
 
6.  **Detailed Explanation:**
    - Provide a comprehensive explanation of the proposed changes.
    - Clarify **why** this approach was chosen (e.g., leveraging existing patterns, minimizing changes, performance considerations).
    - Explain how the new code integrates with the existing system architecture.
    - Mention any potential impacts on other parts of the application or any trade-offs made in the proposed solution.
 
## Important Considerations
 
- Base **all** recommendations directly on the provided source code.
- Maintain consistency with the project's existing architecture, patterns, naming conventions, and coding style.
- Be precise and unambiguous in your instructions and explanations.
- Ensure the final generated plan is formatted using Markdown.
 
---
 
## Here is the specific task you need to plan:
 
**[PLACEHOLDER: Insert the specific feature request or modification task here.]**
 
---

{
    "output": {
      "filePath": ".repomix/output/architecture-docs.xml",
      "style": "xml",
      "parsableStyle": true,
      "compress": false,
      "headerText": "Custom header text",
      "instructionFilePath": ".repomix/instructions/architecture-docs.md",
      "fileSummary": true,
      "directoryStructure": true,
      "removeComments": false,
      "removeEmptyLines": false,
      "topFilesLength": 5,
      "showLineNumbers": false,
      "copyToClipboard": false,
      "includeEmptyDirectories": false,
      "git": {
        "sortByChanges": true,
        "sortByChangesMaxCommits": 100
      }
    },
    "include": ["**/*"],
    "ignore": {
      "useGitignore": true,
      "useDefaultPatterns": true,
      "customPatterns": ["./repomix/**", "tmp/", "*.log", "storage/**", ".github/**", "artisan", "bootstrap/cache/**"]
    },
    "security": {
      "enableSecurityCheck": true
    }
  }

## AI Agent Instructions: Architecture Documentation Generation
 
### Role
 
You are an AI assistant specializing in code analysis and the generation of software architecture documentation.
 
### Context
 
You will be provided with the **complete source code** of a software project.
 
### Objective
 
Your primary objective is to analyze the provided codebase and generate comprehensive architecture documentation covering the key aspects listed below. Your analysis and documentation **must** be derived directly from the provided source code.
 
### Required Documentation Sections
 
Your generated documentation **must** include the following sections, clearly delineated:
 
1.  **High-Level Overview:**
 
    - Provide a concise summary of the system's primary purpose and its main functionalities as inferred from the code.
    - Describe the overall architectural style identified (e.g., monolithic, microservices, client-server, event-driven, layered).
    - List the core technologies, programming languages, frameworks, and significant libraries used in the project.
 
2.  **Component Interactions:**
 
    - Identify the major logical or physical components, modules, services, or layers within the system based on the code structure (e.g., directories, namespaces, classes).
    - Describe how these components interact with each other (e.g., function calls, API requests, events, shared data stores).
    - Where feasible, generate diagrams using Mermaid syntax (e.g., component diagrams, sequence diagrams) to visually represent these interactions. If diagrams are not feasible, provide clear textual descriptions of the communication patterns.
 
3.  **Data Flow Diagrams:**
 
    - Describe the flow of data through the system for key operations or use cases identifiable from the code (e.g., user registration, order processing, data reporting).
    - Explain where data originates (e.g., user input, external systems), how it is processed or transformed by different components, where it is stored (e.g., databases, caches, files), and its eventual destination or output.
    - Generate diagrams using Mermaid syntax (e.g., flowcharts) to illustrate these data flows, or provide detailed textual descriptions if diagrams are not practical.
 
4.  **Design Decisions and Rationale:**
 
    - Infer significant design decisions based on the code structure, chosen libraries/frameworks, observed design patterns (e.g., MVC, Repository, Singleton), and any explicit comments.
    - For each identified decision, attempt to explain the likely rationale behind it (e.g., "The use of framework X suggests a focus on rapid development," "The Repository pattern likely aims to decouple data access logic").
    - Clearly state when a rationale is an inference based on common practices versus explicitly mentioned in comments.
 
5.  **System Constraints and Limitations:**
    - Identify potential system constraints, external dependencies, or limitations evident from the code.
    - Examples include: reliance on specific external APIs or services, assumptions about the deployment environment (e.g., OS-specific calls), potential scalability bottlenecks suggested by algorithms or data handling, areas where the code structure might limit future flexibility.
 
### Important Considerations
 
- Base **all** documentation strictly on the provided source code and its structure.
- Use clear, concise, and objective language.
- Structure the output logically with clear headings for each required section.
- **Ensure the final generated documentation is formatted using Markdown.**
- When generating diagrams (Mermaid), ensure they accurately reflect the interactions or flows derived from the code.
- If information for a section cannot be reasonably inferred from the code, state that explicitly.
- Make sure you are using the correct Mermaid syntax for the diagrams. Don't use weird characters like `>` or `<` in the diagrams.