# cleaniquecoders/db-schema-auditor architecture

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

- Interactive diagram: https://gitdiagram.com/cleaniquecoders/db-schema-auditor
- Repository: https://github.com/cleaniquecoders/db-schema-auditor

## Overview

1. **Project type and runtime boundary**
   - This is a **Laravel package** for auditing database schema design, meant to be installed as a dev dependency in an existing Laravel application.
   - The package enters the host app through Laravel’s **service provider**, **facade**, and an **Artisan command**, rather than running as a standalone app.

2. **Primary entry point**
   - The main user-facing entry point is `src/Commands/DbSchemaAuditorCommand.php`, exposed as `php artisan db:audit`.
   - That command orchestrates the audit flow and switches behavior based on CLI flags like `--models`, `--format`, `--generate-fixes`, `--save-database`, and `--connection`.

3. **Core orchestration layer**
   - `src/DbSchemaAuditor.php` acts as the package’s central service/facade target.
   - `src/DbSchemaAuditorServiceProvider.php` wires the package into Laravel’s container, config, migrations, and command registration.
   - `src/Facades/DbSchemaAuditor.php` provides a Laravel-style static access point for consumers.

4. **Audit pipeline**
   - The audit is decomposed into actions under `src/Actions/`, each handling a distinct stage:
     - `AuditDatabaseIntegrityAction` performs the database schema and integrity checks.
     - `AnalyzeModelRelationshipsAction` inspects Laravel model relationships when `--models` is enabled.
     - `GenerateFixMigrationsAction` creates suggested repair migrations when `--generate-fixes` is enabled.
     - `SaveAuditResultsToDatabaseAction` persists results when `--save-database` is enabled.
   - This separation makes the audit flow composable and keeps database inspection, model analysis, remediation generation, and persistence distinct.

5. **Database abstraction boundary**
   - Database-specific behavior is isolated in `src/Adapters/`.
   - `AbstractDatabaseAdapter` defines the common schema-inspection contract, while concrete adapters implement support for:
     - MySQL
     - PostgreSQL
     - SQL Server
     - Oracle
     - SQLite
   - This is the main portability layer: the audit actions talk to adapters, not directly to a specific database dialect.

6. **Output/reporting layer**
   - Formatting is handled in `src/Formatters/`.
   - `AbstractFormatter` is the shared contract, with concrete formatters for:
     - console
     - JSON
     - Markdown
     - CSV
     - HTML
   - The command selects a formatter based on `--format`, so the reporting concern is separate from the audit logic itself.

7. **Persistence model**
   - Results saved via `--save-database` are represented by Eloquent models in `src/Models/`:
     - `DbAudit`
     - `DbAuditIssue`
     - `DbAuditModelAnalysis`
   - These models support audit history, issue tracking, and model-analysis records stored in the host application database.

8. **Configuration and schema artifacts**
   - Package configuration lives in `config/db-schema-auditor.php`.
   - A migration stub in `database/migrations/create_db_audits_table.php.stub` defines the audit storage tables published into the host app.
   - `database/factories/ModelFactory.php` supports test data generation for package testing.

9. **Generated artifacts and filesystem outputs**
   - The `database/audit/` directory is the default file output location for generated reports, especially JSON/Markdown/CSV/HTML exports.
   - The `README` shows that output path can be redirected, so report generation is a file-output concern separate from database persistence.

10. **External dependencies and integration points**
   - The package depends on Laravel’s command bus/container, Eloquent models, migrations, and filesystem/reporting conventions.
   - It also integrates with the currently configured database connection, with support for selecting an alternate connection via `--connection`.

11. **Quality and validation boundary**
   - Tests under `tests/` cover both architecture constraints and unit behavior:
     - `tests/ArchTest.php` enforces structural rules.
     - `tests/Unit/DatabaseAuditTest.php` covers audit behavior.
   - This indicates the package treats architecture and package shape as part of its public contract.

12. **Tooling and delivery pipeline**
   - Composer is the package manager/runtime integration mechanism.
   - GitHub Actions handle tests, PHPStan static analysis, code style fixes, changelog updates, and dependabot automation.
   - These are supporting concerns, but they matter because this is a distributable package where compatibility and code quality are central.

13. **Overall data flow**
   - The command collects options → the core service coordinates the audit → adapters read schema details from the selected database → optional model analysis inspects Laravel models → formatters render the results → outputs are either printed, written to files, turned into fix migrations, or stored in audit tables.
   - In diagram terms, the key boundary is between **Laravel command/package orchestration** and **database-dialect-specific inspection**.

14. **What to show prominently in an architecture diagram**
   - Show the command as the ingress point.
   - Show a central orchestration service fanning out into four action modules.
   - Show database adapters as a separate polymorphic layer beneath audit actions.
   - Show formatters as a parallel output layer.
   - Show the Eloquent models/database tables as the persistence branch for historical audit tracking.

Main entry points: [`src/Commands/DbSchemaAuditorCommand.php`](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Commands/DbSchemaAuditorCommand.php) (db:audit), [`src/Adapters/AbstractDatabaseAdapter.php`](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/AbstractDatabaseAdapter.php) (DB adapter), [`src/DbSchemaAuditor.php`](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/DbSchemaAuditor.php) (Auditor), [`src/Formatters/AbstractFormatter.php`](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/AbstractFormatter.php) (Formatter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Laravel runtime"]
  node_command["db:audit<br/>artisan command"]
  node_service["Auditor<br/>core service"]
  node_provider["Service provider<br/>Laravel provider"]
  node_facade["Auditor facade<br/>Laravel facade"]
end

subgraph group_audit["Audit pipeline"]
  node_audit_integrity["Integrity audit<br/>audit action"]
  node_model_relations["Model analysis<br/>audit action"]
  node_fix_migrations["Fix migrations<br/>audit action"]
  node_save_results["Save results<br/>audit action"]
end

subgraph group_db["Database adapters"]
  node_db_adapter["DB adapter<br/>adapter contract"]
  node_mysql["MySQL<br/>database adapter<br/>[MySqlAdapter.php]"]
  node_pgsql["PostgreSQL<br/>database adapter"]
  node_sqlserver["SQL Server<br/>database adapter"]
  node_oracle["Oracle<br/>database adapter<br/>[OracleAdapter.php]"]
  node_sqlite["SQLite<br/>database adapter<br/>[SqliteAdapter.php]"]
end

subgraph group_output["Reporting"]
  node_formatter["Formatter<br/>format contract"]
  node_console_fmt["Console<br/>formatter"]
  node_json_fmt["JSON<br/>formatter<br/>[JsonFormatter.php]"]
  node_markdown_fmt["Markdown<br/>formatter"]
  node_csv_fmt["CSV<br/>formatter<br/>[CsvFormatter.php]"]
  node_html_fmt["HTML<br/>formatter<br/>[HtmlFormatter.php]"]
end

subgraph group_persistence["Persistence"]
  node_db_audit[("DbAudit<br/>eloquent model<br/>[DbAudit.php]")]
  node_db_issue[("DbAuditIssue<br/>eloquent model<br/>[DbAuditIssue.php]")]
  node_model_analysis[("DbAuditModelAnalysis<br/>eloquent model")]
end

node_provider -->|"registers"| node_command
node_provider -->|"binds"| node_service
node_provider -.->|"exposes"| node_facade
node_facade -->|"delegates to"| node_service
node_command -->|"invokes"| node_service
node_command -->|"selects"| node_formatter
node_service -->|"runs"| node_audit_integrity
node_service -.->|"optionally runs"| node_model_relations
node_service -.->|"optionally runs"| node_fix_migrations
node_service -.->|"optionally runs"| node_save_results
node_audit_integrity -->|"reads through"| node_db_adapter
node_model_relations -->|"reads through"| node_db_adapter
node_db_adapter -->|"implemented by"| node_mysql
node_db_adapter -->|"implemented by"| node_pgsql
node_db_adapter -->|"implemented by"| node_sqlserver
node_db_adapter -->|"implemented by"| node_oracle
node_db_adapter -->|"implemented by"| node_sqlite
node_command -->|"default output"| node_console_fmt
node_command -->|"supports"| node_json_fmt
node_command -->|"supports"| node_markdown_fmt
node_command -->|"supports"| node_csv_fmt
node_command -->|"supports"| node_html_fmt
node_formatter -->|"implemented by"| node_console_fmt
node_formatter -->|"implemented by"| node_json_fmt
node_formatter -->|"implemented by"| node_markdown_fmt
node_formatter -->|"implemented by"| node_csv_fmt
node_formatter -->|"implemented by"| node_html_fmt
node_save_results -->|"stores"| node_db_audit
node_save_results -->|"stores"| node_db_issue
node_save_results -->|"stores"| node_model_analysis

click node_command "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Commands/DbSchemaAuditorCommand.php"
click node_service "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/DbSchemaAuditor.php"
click node_provider "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/DbSchemaAuditorServiceProvider.php"
click node_facade "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Facades/DbSchemaAuditor.php"
click node_audit_integrity "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/AuditDatabaseIntegrityAction.php"
click node_model_relations "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/AnalyzeModelRelationshipsAction.php"
click node_fix_migrations "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/GenerateFixMigrationsAction.php"
click node_save_results "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/SaveAuditResultsToDatabaseAction.php"
click node_db_adapter "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/AbstractDatabaseAdapter.php"
click node_mysql "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/MySqlAdapter.php"
click node_pgsql "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/PostgreSqlAdapter.php"
click node_sqlserver "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/SqlServerAdapter.php"
click node_oracle "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/OracleAdapter.php"
click node_sqlite "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/SqliteAdapter.php"
click node_formatter "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/AbstractFormatter.php"
click node_console_fmt "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/ConsoleFormatter.php"
click node_json_fmt "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/JsonFormatter.php"
click node_markdown_fmt "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/MarkdownFormatter.php"
click node_csv_fmt "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/CsvFormatter.php"
click node_html_fmt "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/HtmlFormatter.php"
click node_db_audit "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAudit.php"
click node_db_issue "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAuditIssue.php"
click node_model_analysis "https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAuditModelAnalysis.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_command,node_service,node_provider,node_facade toneBlue
class node_audit_integrity,node_model_relations,node_fix_migrations,node_save_results toneAmber
class node_db_adapter,node_mysql,node_pgsql,node_sqlserver,node_oracle,node_sqlite toneMint
class node_formatter,node_console_fmt,node_json_fmt,node_markdown_fmt,node_csv_fmt,node_html_fmt toneRose
class node_db_audit,node_db_issue,node_model_analysis toneIndigo
```

## Components

### Laravel runtime

Package entry points and orchestration inside the host Laravel app

- [db:audit](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Commands/DbSchemaAuditorCommand.php): artisan command · Main CLI entry point that parses options and starts the audit · `src/Commands/DbSchemaAuditorCommand.php`
- [Auditor](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/DbSchemaAuditor.php): core service · Central coordinator used by the command and facade · `src/DbSchemaAuditor.php`
- [Service provider](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/DbSchemaAuditorServiceProvider.php): Laravel provider · Registers bindings, config, migrations, and commands · `src/DbSchemaAuditorServiceProvider.php`
- [Auditor facade](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Facades/DbSchemaAuditor.php): Laravel facade · Static access point to the core service · `src/Facades/DbSchemaAuditor.php`

### Audit pipeline

Core audit stages and their execution flow

- [Integrity audit](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/AuditDatabaseIntegrityAction.php): audit action · Checks database schema structure and integrity · `src/Actions/AuditDatabaseIntegrityAction.php`
- [Model analysis](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/AnalyzeModelRelationshipsAction.php): audit action · Inspects Laravel model relationships when enabled · `src/Actions/AnalyzeModelRelationshipsAction.php`
- [Fix migrations](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/GenerateFixMigrationsAction.php): audit action · Generates suggested repair migrations · `src/Actions/GenerateFixMigrationsAction.php`
- [Save results](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Actions/SaveAuditResultsToDatabaseAction.php): audit action · Persists audit output to the host application database · `src/Actions/SaveAuditResultsToDatabaseAction.php`

### Database adapters

Database-dialect-specific schema inspection boundary

- [DB adapter](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/AbstractDatabaseAdapter.php): adapter contract · Common schema-inspection abstraction used by audit actions · `src/Adapters/AbstractDatabaseAdapter.php`
- [MySQL](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/MySqlAdapter.php): database adapter · MySQL-specific schema inspection implementation · `src/Adapters/MySqlAdapter.php`
- [PostgreSQL](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/PostgreSqlAdapter.php): database adapter · PostgreSQL-specific schema inspection implementation · `src/Adapters/PostgreSqlAdapter.php`
- [SQL Server](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/SqlServerAdapter.php): database adapter · SQL Server-specific schema inspection implementation · `src/Adapters/SqlServerAdapter.php`
- [Oracle](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/OracleAdapter.php): database adapter · Oracle-specific schema inspection implementation · `src/Adapters/OracleAdapter.php`
- [SQLite](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Adapters/SqliteAdapter.php): database adapter · SQLite-specific schema inspection implementation · `src/Adapters/SqliteAdapter.php`

### Reporting

Result formatting and report generation

- [Formatter](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/AbstractFormatter.php): format contract · Shared output formatting abstraction · `src/Formatters/AbstractFormatter.php`
- [Console](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/ConsoleFormatter.php): formatter · Human-readable terminal output · `src/Formatters/ConsoleFormatter.php`
- [JSON](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/JsonFormatter.php): formatter · Structured JSON report output · `src/Formatters/JsonFormatter.php`
- [Markdown](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/MarkdownFormatter.php): formatter · Markdown report output · `src/Formatters/MarkdownFormatter.php`
- [CSV](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/CsvFormatter.php): formatter · Tabular CSV report output · `src/Formatters/CsvFormatter.php`
- [HTML](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Formatters/HtmlFormatter.php): formatter · HTML report output · `src/Formatters/HtmlFormatter.php`

### Persistence

Audit history and stored analysis records

- [DbAudit](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAudit.php): eloquent model · Stored audit run record · `src/Models/DbAudit.php`
- [DbAuditIssue](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAuditIssue.php): eloquent model · Stored audit issue record · `src/Models/DbAuditIssue.php`
- [DbAuditModelAnalysis](https://github.com/cleaniquecoders/db-schema-auditor/blob/main/src/Models/DbAuditModelAnalysis.php): eloquent model · Stored model relationship analysis record · `src/Models/DbAuditModelAnalysis.php`

## Connections

- Service provider → db:audit: registers · Service provider registers the Artisan command
- Service provider → Auditor: binds · Service provider binds the core auditor into the container
- Service provider → Auditor facade: exposes · Provider makes the package available through Laravel conventions
- Auditor facade → Auditor: delegates to · Facade resolves the core auditor service
- db:audit → Auditor: invokes · Command orchestrates the audit through the core service
- db:audit → Formatter: selects · Command chooses a formatter based on CLI flags
- Auditor → Integrity audit: runs · Core service coordinates the database integrity audit
- Auditor → Model analysis: optionally runs · Core service triggers model analysis when enabled
- Auditor → Fix migrations: optionally runs · Core service triggers fix generation when enabled
- Auditor → Save results: optionally runs · Core service triggers persistence when enabled
- Integrity audit → DB adapter: reads through · Integrity checks use the database abstraction boundary
- Model analysis → DB adapter: reads through · Model analysis may inspect the selected database connection
- DB adapter → MySQL: implemented by · Concrete adapter for MySQL
- DB adapter → PostgreSQL: implemented by · Concrete adapter for PostgreSQL
- DB adapter → SQL Server: implemented by · Concrete adapter for SQL Server
- DB adapter → Oracle: implemented by · Concrete adapter for Oracle
- DB adapter → SQLite: implemented by · Concrete adapter for SQLite
- db:audit → Console: default output · Console formatting is the terminal-facing report mode
- db:audit → JSON: supports · Command can emit JSON reports
- db:audit → Markdown: supports · Command can emit Markdown reports
- db:audit → CSV: supports · Command can emit CSV reports
- db:audit → HTML: supports · Command can emit HTML reports
- Formatter → Console: implemented by · Concrete console formatter
- Formatter → JSON: implemented by · Concrete JSON formatter
- Formatter → Markdown: implemented by · Concrete Markdown formatter
- Formatter → CSV: implemented by · Concrete CSV formatter
- Formatter → HTML: implemented by · Concrete HTML formatter
- Save results → DbAudit: stores · Audit runs are persisted as records
- Save results → DbAuditIssue: stores · Issues are persisted as records
- Save results → DbAuditModelAnalysis: stores · Model analysis results are persisted as records