cleaniquecoders/db-schema-auditor

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.