# itsshashanksp/generic_sql_api_framework architecture

> Architecture diagram of the GitHub repository itsshashanksp/generic_sql_api_framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsshashanksp/generic_sql_api_framework
- Repository: https://github.com/itsshashanksp/generic_sql_api_framework

## Overview

Generic SQL REST API Framework: clients submit JSON actions to a shared API, which authenticates and authorizes requests, validates them, executes database operations, and returns a request-ID JSON response. The graph also preserves the separate Admin management plane, health checks, SQL-to-request parser, and application backup/recovery. Several subsystem links are documented by the README; source-level links use the sampled SOURCE INDEX or excerpts, so unsampled wiring is not inferred.

Main entry points: [`api/index.php`](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/api/index.php) (JSON API entry), [`app/Repositories/QueryRepository.php`](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Repositories/QueryRepository.php) (Query construction), [`core/Database.php`](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/Database.php) (Database connection), [`admin/api.php`](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/admin/api.php) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_api_entry["JSON API entry<br/>[index.php]"]
  node_authentication["Authentication"]
  node_authorization["Role authorization"]
  node_request_validation["Request validation"]
  node_query_controller["Query controller"]
  node_response["JSON response envelope<br/>[Response.php]"]
end

subgraph group_data["Data access"]
  node_query_service["Query service<br/>[QueryService.php]"]
  node_query_repository["Query construction"]
  node_sql_execution["SQL execution<br/>[QueryEngine.php]"]
  node_database["Database connection<br/>[Database.php]"]
  node_driver_factory["Driver factory<br/>[DriverFactory.php]"]
  node_metadata["Database metadata"]
  node_writes["Generic CRUD<br/>[WriteService.php]"]
  node_sql_resources["SQL Resources"]
end

subgraph group_management["Administration"]
  node_admin_api["Admin API<br/>[api.php]"]
  node_admin_console["Admin Console<br/>[index.php]"]
  node_backup_recovery["Backup and recovery"]
  node_runtime_configuration["Runtime configuration"]
end

subgraph group_support["Auxiliary services"]
  node_health["Health endpoints<br/>[health.php]"]
  node_parser_entry["SQL parser endpoint<br/>[index.php]"]
  node_parser_handler["Parser request handler"]
  node_parser["SQL-to-JSON parser<br/>[SqlParser.php]"]
end

node_client(("Client application"))
node_sql_database[("SQL database")]
node_admin_actor(("System administrator"))

node_client -->|"submits JSON"| node_api_entry
node_api_entry -->|"runs middleware"| node_authentication
node_api_entry -->|"validates requests"| node_request_validation
node_api_entry -->|"dispatches actions"| node_query_controller
node_authentication -.->|"resolves principal"| node_authorization
node_query_controller -->|"calls service"| node_query_service
node_query_service -->|"delegates queries"| node_query_repository
node_query_repository -->|"executes SQL"| node_sql_execution
node_sql_execution -->|"uses connection"| node_database
node_database -->|"creates driver"| node_driver_factory
node_database -->|"runs statements"| node_sql_database
node_query_repository -->|"uses catalog"| node_metadata
node_client -->|"requests CRUD"| node_writes
node_client -->|"requests metadata"| node_metadata
node_client -->|"requests resource"| node_sql_resources
node_admin_actor -->|"manages system"| node_admin_api
node_admin_actor -->|"uses console"| node_admin_console
node_admin_api -.->|"controls settings"| node_runtime_configuration
node_admin_api -.->|"manages backups"| node_backup_recovery
node_client -->|"checks health"| node_health
node_client -->|"submits SQL"| node_parser_entry
node_parser_entry -->|"routes request"| node_parser_handler
node_parser_handler -.->|"parses SQL"| node_parser
node_parser_handler -->|"emits JSON"| node_response
node_api_entry -->|"returns envelope"| node_response

click node_api_entry "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/api/index.php"
click node_authentication "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Middleware/AuthenticationMiddleware.php"
click node_authorization "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/AuthorizationService.php"
click node_request_validation "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Requests/QueryRequestValidator.php"
click node_query_controller "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Controllers/QueryController.php"
click node_query_service "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/QueryService.php"
click node_query_repository "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Repositories/QueryRepository.php"
click node_sql_execution "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/QueryEngine.php"
click node_database "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/Database.php"
click node_driver_factory "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/database/factory/DriverFactory.php"
click node_metadata "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Repositories/MetadataRepository.php"
click node_writes "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/WriteService.php"
click node_sql_resources "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Resources/SqlResourceDiscovery.php"
click node_admin_api "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/admin/api.php"
click node_admin_console "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/admin/index.php"
click node_backup_recovery "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Backup/BackupRecoveryService.php"
click node_runtime_configuration "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Configuration/RuntimeConfiguration.php"
click node_health "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/api/health.php"
click node_parser_entry "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/index.php"
click node_parser_handler "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/src/SqlParserRequestHandler.php"
click node_parser "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/src/SqlParser.php"
click node_response "https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/Response.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_api_entry,node_authentication,node_authorization,node_request_validation,node_query_controller,node_response,node_client toneBlue
class node_query_service,node_query_repository,node_sql_execution,node_database,node_driver_factory,node_metadata,node_writes,node_sql_resources,node_sql_database toneAmber
class node_admin_api,node_admin_console,node_backup_recovery,node_runtime_configuration toneMint
class node_health,node_parser_entry,node_parser_handler,node_parser toneRose
class node_admin_actor toneIndigo
```

## Components

### API runtime

- [JSON API entry](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/api/index.php): `api/index.php`
- [Authentication](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Middleware/AuthenticationMiddleware.php): `app/Middleware/AuthenticationMiddleware.php`
- [Role authorization](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/AuthorizationService.php): `app/Services/AuthorizationService.php`
- [Request validation](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Requests/QueryRequestValidator.php): `app/Requests/QueryRequestValidator.php`
- [Query controller](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Controllers/QueryController.php): `app/Controllers/QueryController.php`
- [JSON response envelope](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/Response.php): `core/Response.php`

### Data access

- [Query service](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/QueryService.php): `app/Services/QueryService.php`
- [Query construction](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Repositories/QueryRepository.php): `app/Repositories/QueryRepository.php`
- [SQL execution](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/QueryEngine.php): `core/QueryEngine.php`
- [Database connection](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/core/Database.php): `core/Database.php`
- [Driver factory](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/database/factory/DriverFactory.php): `database/factory/DriverFactory.php`
- [Database metadata](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Repositories/MetadataRepository.php): `app/Repositories/MetadataRepository.php`
- [Generic CRUD](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Services/WriteService.php): `app/Services/WriteService.php`
- [SQL Resources](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Resources/SqlResourceDiscovery.php): `app/Resources/SqlResourceDiscovery.php`

### Administration

- [Admin API](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/admin/api.php): `admin/api.php`
- [Admin Console](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/admin/index.php): `admin/index.php`
- [Backup and recovery](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Backup/BackupRecoveryService.php): `app/Backup/BackupRecoveryService.php`
- [Runtime configuration](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/app/Configuration/RuntimeConfiguration.php): `app/Configuration/RuntimeConfiguration.php`

### Auxiliary services

- [Health endpoints](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/api/health.php): `api/health.php`
- [SQL parser endpoint](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/index.php): `sqlparser/index.php`
- [Parser request handler](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/src/SqlParserRequestHandler.php): `sqlparser/src/SqlParserRequestHandler.php`
- [SQL-to-JSON parser](https://github.com/itsshashanksp/generic_sql_api_framework/blob/dev/sqlparser/src/SqlParser.php): `sqlparser/src/SqlParser.php`

### Other components

- **Client application**
- **SQL database**
- **System administrator**

## Connections

- Client application → JSON API entry: submits JSON (evidence: `README.md`)
- JSON API entry → Authentication: runs middleware (evidence: `api/index.php`)
- JSON API entry → Request validation: validates requests (evidence: `api/index.php`)
- JSON API entry → Query controller: dispatches actions (evidence: `api/index.php`)
- Authentication → Role authorization: resolves principal
- Query controller → Query service: calls service (evidence: `app/Controllers/QueryController.php`)
- Query service → Query construction: delegates queries (evidence: `app/Services/QueryService.php`)
- Query construction → SQL execution: executes SQL (evidence: `app/Repositories/QueryRepository.php`)
- SQL execution → Database connection: uses connection (evidence: `core/QueryEngine.php`)
- Database connection → Driver factory: creates driver (evidence: `core/Database.php`)
- Database connection → SQL database: runs statements (evidence: `README.md`)
- Query construction → Database metadata: uses catalog (evidence: `app/Repositories/QueryRepository.php`)
- Client application → Generic CRUD: requests CRUD (evidence: `README.md`)
- Client application → Database metadata: requests metadata (evidence: `README.md`)
- Client application → SQL Resources: requests resource (evidence: `README.md`)
- System administrator → Admin API: manages system (evidence: `README.md`)
- System administrator → Admin Console: uses console (evidence: `README.md`)
- Admin API → Runtime configuration: controls settings
- Admin API → Backup and recovery: manages backups
- Client application → Health endpoints: checks health (evidence: `README.md`)
- Client application → SQL parser endpoint: submits SQL (evidence: `README.md`)
- SQL parser endpoint → Parser request handler: routes request (evidence: `sqlparser/index.php`)
- Parser request handler → SQL-to-JSON parser: parses SQL
- Parser request handler → JSON response envelope: emits JSON (evidence: `sqlparser/src/SqlParserRequestHandler.php`)
- JSON API entry → JSON response envelope: returns envelope (evidence: `README.md`)
