# sagor-roy/laravel-comments architecture

> Architecture diagram of the GitHub repository sagor-roy/laravel-comments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagor-roy/laravel-comments
- Repository: https://github.com/sagor-roy/laravel-comments

## Overview

1. **Overall shape**
   - This is a **Laravel 13 package** that adds a reusable comment system to a host application.
   - It is not a standalone app: the host app opts in by adding a trait to any Eloquent model and rendering the package’s Blade view/directive.

2. **Integration boundary with the host app**
   - The main integration point is `SagorRoy\Comments\Traits\Commentable`.
   - Any model using that trait becomes “commentable,” which means the package can attach comments to arbitrary content types, not just one specific model.

3. **Package bootstrap**
   - `src/CommentServiceProvider.php` is the central wiring point.
   - It is responsible for registering the package’s routes, views, config, translations, migrations, and publishable assets so the package can be installed and customized inside a Laravel app.

4. **HTTP/API surface**
   - `src/routes/web.php` defines the web-facing endpoints used by the comment UI.
   - `src/Http/Controllers/CommentController.php` handles comment actions, and `src/Http/Requests/StoreCommentRequest.php` provides request validation for submissions.
   - The architecture is web-route based, with AJAX submission from the client rather than a separate API layer.

5. **Persistence layer**
   - `src/Models/Comment.php` is the package’s Eloquent model.
   - `src/database/migrations/2025_01_01_000000_create_comments_table.php` defines the comments table.
   - The data model supports storing comments plus reply relationships, which is what enables one level of nesting.

6. **Comment hierarchy and threading**
   - The package explicitly supports **one level of nested replies** only.
   - The presence of a reply form partial and the README constraints imply a parent/reply relationship in the comment data model, but replies to replies are intentionally blocked.

7. **Rendering layer**
   - `src/resources/views/comments.blade.php` is the main UI entry point.
   - `src/resources/views/partials/_comment.blade.php`, `_form.blade.php`, and `_reply-form.blade.php` break the interface into reusable chunks for listing comments, creating new comments, and replying.
   - This indicates a server-rendered Blade UI, enhanced rather than replaced by JavaScript.

8. **Client-side behavior**
   - `src/resources/views/comments.js` provides the AJAX behavior for submission and likely UI updates after posting.
   - `public/css/comments.css` styles the comment widget.
   - The package is designed so the host app includes both the CSS and JS as published assets.

9. **Configuration and localization**
   - `src/config/comments.php` defines package behavior such as max length, per-page count, guest rules, and the user model class.
   - `src/lang/en/comments.php` provides the package’s user-facing strings.
   - These are meant to be publishable and overrideable by the host app, which is typical Laravel package architecture.

10. **Behavioral rules**
   - Guest comments are allowed, with optional guest name requirements controlled by config.
   - Authenticated users are auto-associated with their identity.
   - The README also states users can only delete their own comments, so authorization is enforced in the controller/model flow.

11. **What an architecture diagram should emphasize**
   - The central flow is: **host model with `Commentable` trait → Blade comments widget → AJAX request → controller/request validation → Comment model/database → updated rendered thread**.
   - The important boundaries are the **package vs. host app**, the **server-rendered Blade UI vs. AJAX client behavior**, and the **single-model comment storage vs. polymorphic usage across many Eloquent models**.

Main entry points: [`src/CommentServiceProvider.php`](https://github.com/sagor-roy/laravel-comments/blob/master/src/CommentServiceProvider.php) (Service provider), [`src/resources/views/comments.blade.php`](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/comments.blade.php) (Comments widget), [`src/Http/Controllers/CommentController.php`](https://github.com/sagor-roy/laravel-comments/blob/master/src/Http/Controllers/CommentController.php) (Comment controller), [`src/Models/Comment.php`](https://github.com/sagor-roy/laravel-comments/blob/master/src/Models/Comment.php) (Comment model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host app"]
  node_host_model["Eloquent model<br/>host model"]
end

subgraph group_package["Comments package"]
  node_trait["Commentable<br/>trait<br/>[Commentable.php]"]
  node_provider["Service provider<br/>package bootstrap"]
end

subgraph group_ui["Rendering layer"]
  node_widget["Comments widget<br/>Blade view<br/>[comments.blade.php]"]
  node_comment_partial["Comment item<br/>Blade partial<br/>[_comment.blade.php]"]
  node_form_partial["New comment<br/>Blade partial<br/>[_form.blade.php]"]
  node_reply_partial["Reply form<br/>Blade partial"]
  node_js["Comments JS<br/>client script<br/>[comments.js]"]
  node_css["Comments CSS<br/>stylesheet<br/>[comments.css]"]
end

subgraph group_backend["Request flow"]
  node_routes["Web routes<br/>route file<br/>[web.php]"]
  node_controller["Comment controller<br/>HTTP controller"]
  node_request["Store request<br/>form request"]
end

subgraph group_data["Persistence"]
  node_comment_model[("Comment model<br/>Eloquent model<br/>[Comment.php]")]
  node_migration["Comments table<br/>migration"]
end

subgraph group_support["Support files"]
  node_config["Package config<br/>[comments.php]"]
  node_lang["Translations<br/>language file<br/>[comments.php]"]
end

node_host_model -->|"uses"| node_trait
node_provider -->|"registers"| node_routes
node_provider -->|"registers views"| node_widget
node_provider -->|"publishes/loads"| node_config
node_provider -->|"loads"| node_lang
node_provider -->|"loads"| node_migration
node_provider -->|"publishes"| node_css
node_trait -->|"relates to"| node_comment_model
node_routes -->|"dispatches to"| node_controller
node_controller -->|"validates with"| node_request
node_controller -->|"creates/reads"| node_comment_model
node_comment_model -->|"stored in"| node_migration
node_widget -->|"includes"| node_comment_partial
node_widget -->|"includes"| node_form_partial
node_comment_partial -->|"includes"| node_reply_partial
node_widget -->|"enhanced by"| node_js
node_widget -->|"styled by"| node_css
node_js -->|"submits to"| node_controller
node_config -.->|"governs rules"| node_controller
node_comment_model -->|"belongs to"| node_host_model

click node_trait "https://github.com/sagor-roy/laravel-comments/blob/master/src/Traits/Commentable.php"
click node_provider "https://github.com/sagor-roy/laravel-comments/blob/master/src/CommentServiceProvider.php"
click node_routes "https://github.com/sagor-roy/laravel-comments/blob/master/src/routes/web.php"
click node_controller "https://github.com/sagor-roy/laravel-comments/blob/master/src/Http/Controllers/CommentController.php"
click node_request "https://github.com/sagor-roy/laravel-comments/blob/master/src/Http/Requests/StoreCommentRequest.php"
click node_widget "https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/comments.blade.php"
click node_comment_partial "https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_comment.blade.php"
click node_form_partial "https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_form.blade.php"
click node_reply_partial "https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_reply-form.blade.php"
click node_js "https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/comments.js"
click node_css "https://github.com/sagor-roy/laravel-comments/blob/master/public/css/comments.css"
click node_comment_model "https://github.com/sagor-roy/laravel-comments/blob/master/src/Models/Comment.php"
click node_migration "https://github.com/sagor-roy/laravel-comments/blob/master/src/database/migrations/2025_01_01_000000_create_comments_table.php"
click node_config "https://github.com/sagor-roy/laravel-comments/blob/master/src/config/comments.php"
click node_lang "https://github.com/sagor-roy/laravel-comments/blob/master/src/lang/en/comments.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_model toneBlue
class node_trait,node_provider toneAmber
class node_widget,node_comment_partial,node_form_partial,node_reply_partial,node_js,node_css toneMint
class node_routes,node_controller,node_request toneRose
class node_comment_model,node_migration toneIndigo
class node_config,node_lang toneTeal
```

## Components

### Host app

External Laravel application that opts into comments by using the package trait and rendering the widget.

- **Eloquent model**: host model · Any host application model that opts into comments.

### Comments package

Reusable Laravel package code shipped under src/.

- [Commentable](https://github.com/sagor-roy/laravel-comments/blob/master/src/Traits/Commentable.php): trait · Adds commentable behavior to host models. · `src/Traits/Commentable.php`
- [Service provider](https://github.com/sagor-roy/laravel-comments/blob/master/src/CommentServiceProvider.php): package bootstrap · Registers routes, views, config, translations, migrations, and publishable assets. · `src/CommentServiceProvider.php`

### Rendering layer

Server-rendered Blade widget and client-side behavior for comment interaction.

- [Comments widget](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/comments.blade.php): Blade view · Main server-rendered comment UI entry point. · `src/resources/views/comments.blade.php`
- [Comment item](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_comment.blade.php): Blade partial · Renders a single comment and its nested reply area. · `src/resources/views/partials/_comment.blade.php`
- [New comment](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_form.blade.php): Blade partial · Renders the main comment form. · `src/resources/views/partials/_form.blade.php`
- [Reply form](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/partials/_reply-form.blade.php): Blade partial · Renders the one-level reply form. · `src/resources/views/partials/_reply-form.blade.php`
- [Comments JS](https://github.com/sagor-roy/laravel-comments/blob/master/src/resources/views/comments.js): client script · AJAX submission and post-submit UI behavior. · `src/resources/views/comments.js`
- [Comments CSS](https://github.com/sagor-roy/laravel-comments/blob/master/public/css/comments.css): stylesheet · Styles for the comment widget. · `public/css/comments.css`

### Request flow

HTTP entry points, validation, and controller logic for comment actions.

- [Web routes](https://github.com/sagor-roy/laravel-comments/blob/master/src/routes/web.php): route file · Web-facing endpoints for comment actions. · `src/routes/web.php`
- [Comment controller](https://github.com/sagor-roy/laravel-comments/blob/master/src/Http/Controllers/CommentController.php): HTTP controller · Handles comment submission and related actions. · `src/Http/Controllers/CommentController.php`
- [Store request](https://github.com/sagor-roy/laravel-comments/blob/master/src/Http/Requests/StoreCommentRequest.php): form request · Validates incoming comment submissions. · `src/Http/Requests/StoreCommentRequest.php`

### Persistence

Comment model and migration that store threaded comments.

- [Comment model](https://github.com/sagor-roy/laravel-comments/blob/master/src/Models/Comment.php): Eloquent model · Package model for stored comments and thread relationships. · `src/Models/Comment.php`
- [Comments table](https://github.com/sagor-roy/laravel-comments/blob/master/src/database/migrations/2025_01_01_000000_create_comments_table.php): migration · Creates the comments database table. · `src/database/migrations/2025_01_01_000000_create_comments_table.php`

### Support files

Config, translation, and assets used to customize the package.

- [Package config](https://github.com/sagor-roy/laravel-comments/blob/master/src/config/comments.php): config · Controls limits, guest rules, and user model binding. · `src/config/comments.php`
- [Translations](https://github.com/sagor-roy/laravel-comments/blob/master/src/lang/en/comments.php): language file · User-facing strings for the comments package. · `src/lang/en/comments.php`

## Connections

- Eloquent model → Commentable: uses · Host models become commentable by adding the trait.
- Service provider → Web routes: registers · Loads the package web routes.
- Service provider → Comments widget: registers views · Makes the Blade UI available to the host app.
- Service provider → Package config: publishes/loads · Exposes package configuration for customization.
- Service provider → Translations: loads · Registers package translations.
- Service provider → Comments table: loads · Registers the comments migration.
- Service provider → Comments CSS: publishes · Makes the stylesheet publishable as an asset.
- Commentable → Comment model: relates to · Enables polymorphic comment attachment from host models.
- Web routes → Comment controller: dispatches to · Routes comment actions into the controller.
- Comment controller → Store request: validates with · Submission input is checked by the form request.
- Comment controller → Comment model: creates/reads · Controller persists and fetches comments.
- Comment model → Comments table: stored in · The model is backed by the comments table.
- Comments widget → Comment item: includes · The main widget composes comment items.
- Comments widget → New comment: includes · The main widget renders the new comment form.
- Comment item → Reply form: includes · Single-level replies are rendered through the reply form.
- Comments widget → Comments JS: enhanced by · Client-side AJAX behavior augments the server-rendered UI.
- Comments widget → Comments CSS: styled by · The widget uses the published stylesheet.
- Comments JS → Comment controller: submits to · AJAX posts comment actions to the controller.
- Package config → Comment controller: governs rules · Config influences limits, guest comments, and auth behavior.
- Comment model → Eloquent model: belongs to · Comments are associated with arbitrary commentable host models.