# sleepyworkshop/generic_sql_api_framework architecture

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

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

## Overview

Generic SQL API Framework is a PHP backend for validated JSON access to SQL Server, with separate admin and non-executing SQL-parser surfaces. The main workflow validates and normalizes API requests, dispatches them through controllers and services, and builds parameterized database operations. Distinct branches support structured queries, reviewed SQL resources, allow-listed writes, routines, metadata, and authentication/authorization. Admin capabilities include setup, configuration, health, lifecycle controls, and verified application backups. The map follows the README’s architecture; several capability links use documented paths because their implementation was not sampled.

Main entry points: [`app/Services`](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Services) (Application Services), [`app/Repositories/QueryRepository.php`](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/QueryRepository.php) (Query Repository), [`app/Services/AdminService.php`](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Services/AdminService.php) (Admin Services), [`core/QueryEngine.php`](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/core/QueryEngine.php) (Query Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_api_entry["API Entry<br/>[index.php]"]
  node_middleware["Request Middleware"]
  node_validators["Request Validators"]
  node_normalizer["Query Normalizer"]
  node_controllers["API Controllers"]
  node_services["Application Services"]
  node_response["HTTP Response<br/>[Response.php]"]
end

subgraph group_data["Data Access"]
  node_query_repo["Query Repository"]
  node_query_builders["Query Builders"]
  node_sql_resources["Reviewed SQL Resources"]
  node_write_repo["Write Repository"]
  node_metadata["Metadata Repository"]
  node_query_engine["Query Engine<br/>[QueryEngine.php]"]
  node_database["Database Driver"]
end

subgraph group_security["Identity and Access"]
  node_auth["Authentication Services<br/>[AuthService.php]"]
  node_auth_repo["User Repository<br/>[AuthRepository.php]"]
  node_auth_store["Auth Configuration"]
end

subgraph group_admin["Administration"]
  node_admin_entry["Admin Surface<br/>[index.php]"]
  node_admin_api["Admin API Surface<br/>[api.php]"]
  node_admin_services["Admin Services<br/>[AdminService.php]"]
  node_runtime["Runtime Controls"]
  node_backup["Backup Manager"]
end

subgraph group_parser["SQL Parser"]
  node_parser_entry["Parser Entry<br/>[index.php]"]
  node_parser_handler["Parser Handler"]
  node_parser_generator["SQL Generator<br/>[SqlGenerator.php]"]
end

node_client(("API Client"))
node_sqlserver[("SQL Server")]

node_client -->|"submits JSON"| node_api_entry
node_api_entry -->|"runs through"| node_middleware
node_middleware -->|"passes request"| node_validators
node_validators -->|"validates input"| node_normalizer
node_normalizer -->|"normalizes for"| node_controllers
node_controllers -->|"dispatches actions"| node_services
node_services -->|"requests queries"| node_query_repo
node_query_repo -->|"builds statements"| node_query_builders
node_query_builders -->|"returns SQL"| node_query_repo
node_query_repo -->|"executes prepared"| node_query_engine
node_services -->|"resolves resources"| node_sql_resources
node_services -->|"requests writes"| node_write_repo
node_write_repo -->|"executes writes"| node_query_engine
node_services -->|"requests metadata"| node_metadata
node_metadata -->|"queries schema"| node_query_engine
node_query_engine -->|"uses ODBC"| node_database
node_database -->|"executes SQL"| node_sqlserver
node_controllers -->|"handles auth actions"| node_auth
node_middleware -->|"checks identity"| node_auth
node_auth -->|"loads users"| node_auth_repo
node_auth_repo -->|"reads and writes"| node_auth_store
node_client -->|"opens console"| node_admin_entry
node_client -->|"calls admin API"| node_admin_api
node_admin_entry -->|"dispatches admin"| node_admin_services
node_admin_api -->|"dispatches actions"| node_admin_services
node_admin_services -->|"controls services"| node_runtime
node_admin_services -->|"manages backups"| node_backup
node_client -->|"submits SQL"| node_parser_entry
node_parser_entry -->|"handles request"| node_parser_handler
node_parser_handler -->|"generates JSON"| node_parser_generator
node_parser_handler -->|"formats errors"| node_response

click node_api_entry "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/api/index.php"
click node_middleware "https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Middleware"
click node_validators "https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Requests"
click node_normalizer "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Requests/QueryRequestNormalizer.php"
click node_controllers "https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Controllers"
click node_services "https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Services"
click node_query_repo "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/QueryRepository.php"
click node_query_builders "https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Repositories/Query"
click node_sql_resources "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Resources/SqlResourceRegistry.php"
click node_write_repo "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/WriteRepository.php"
click node_metadata "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/MetadataRepository.php"
click node_query_engine "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/core/QueryEngine.php"
click node_database "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/database/drivers/DatabaseDriverInterface.php"
click node_auth "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Services/AuthService.php"
click node_auth_repo "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/AuthRepository.php"
click node_auth_store "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Configuration/RuntimeConfiguration.php"
click node_admin_entry "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/admin/index.php"
click node_admin_api "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/admin/api.php"
click node_admin_services "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Services/AdminService.php"
click node_runtime "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Runtime/ApiProcessManager.php"
click node_backup "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Backup/ApplicationBackupManager.php"
click node_parser_entry "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/index.php"
click node_parser_handler "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/src/SqlParserRequestHandler.php"
click node_parser_generator "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/src/SqlGenerator.php"
click node_response "https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/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_middleware,node_validators,node_normalizer,node_controllers,node_services,node_response,node_client toneBlue
class node_query_repo,node_query_builders,node_sql_resources,node_write_repo,node_metadata,node_query_engine,node_database,node_sqlserver toneAmber
class node_auth,node_auth_repo,node_auth_store toneMint
class node_admin_entry,node_admin_api,node_admin_services,node_runtime,node_backup toneRose
class node_parser_entry,node_parser_handler,node_parser_generator toneIndigo
```

## Components

### Application API

- [API Entry](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/api/index.php): `api/index.php`
- [Request Middleware](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Middleware): `app/Middleware`
- [Request Validators](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Requests): `app/Requests`
- [Query Normalizer](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Requests/QueryRequestNormalizer.php): `app/Requests/QueryRequestNormalizer.php`
- [API Controllers](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Controllers): `app/Controllers`
- [Application Services](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Services): `app/Services`
- [HTTP Response](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/core/Response.php): `core/Response.php`

### Data Access

- [Query Repository](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/QueryRepository.php): `app/Repositories/QueryRepository.php`
- [Query Builders](https://github.com/sleepyworkshop/generic_sql_api_framework/tree/main/app/Repositories/Query): `app/Repositories/Query`
- [Reviewed SQL Resources](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Resources/SqlResourceRegistry.php): `app/Resources/SqlResourceRegistry.php`
- [Write Repository](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/WriteRepository.php): `app/Repositories/WriteRepository.php`
- [Metadata Repository](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/MetadataRepository.php): `app/Repositories/MetadataRepository.php`
- [Query Engine](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/core/QueryEngine.php): `core/QueryEngine.php`
- [Database Driver](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/database/drivers/DatabaseDriverInterface.php): `database/drivers/DatabaseDriverInterface.php`

### Identity and Access

- [Authentication Services](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Services/AuthService.php): `app/Services/AuthService.php`
- [User Repository](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Repositories/AuthRepository.php): `app/Repositories/AuthRepository.php`
- [Auth Configuration](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Configuration/RuntimeConfiguration.php): `app/Configuration/RuntimeConfiguration.php`

### Administration

- [Admin Surface](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/admin/index.php): `admin/index.php`
- [Admin API Surface](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/admin/api.php): `admin/api.php`
- [Admin Services](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Services/AdminService.php): `app/Services/AdminService.php`
- [Runtime Controls](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Runtime/ApiProcessManager.php): `app/Runtime/ApiProcessManager.php`
- [Backup Manager](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/app/Backup/ApplicationBackupManager.php): `app/Backup/ApplicationBackupManager.php`

### SQL Parser

- [Parser Entry](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/index.php): `sqlparser/index.php`
- [Parser Handler](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/src/SqlParserRequestHandler.php): `sqlparser/src/SqlParserRequestHandler.php`
- [SQL Generator](https://github.com/sleepyworkshop/generic_sql_api_framework/blob/main/sqlparser/src/SqlGenerator.php): `sqlparser/src/SqlGenerator.php`

### Other components

- **API Client**
- **SQL Server**

## Connections

- API Client → API Entry: submits JSON
- API Entry → Request Middleware: runs through
- Request Middleware → Request Validators: passes request
- Request Validators → Query Normalizer: validates input
- Query Normalizer → API Controllers: normalizes for
- API Controllers → Application Services: dispatches actions
- Application Services → Query Repository: requests queries
- Query Repository → Query Builders: builds statements
- Query Builders → Query Repository: returns SQL
- Query Repository → Query Engine: executes prepared
- Application Services → Reviewed SQL Resources: resolves resources
- Application Services → Write Repository: requests writes
- Write Repository → Query Engine: executes writes
- Application Services → Metadata Repository: requests metadata
- Metadata Repository → Query Engine: queries schema
- Query Engine → Database Driver: uses ODBC
- Database Driver → SQL Server: executes SQL
- API Controllers → Authentication Services: handles auth actions
- Request Middleware → Authentication Services: checks identity
- Authentication Services → User Repository: loads users
- User Repository → Auth Configuration: reads and writes
- API Client → Admin Surface: opens console
- API Client → Admin API Surface: calls admin API
- Admin Surface → Admin Services: dispatches admin
- Admin API Surface → Admin Services: dispatches actions
- Admin Services → Runtime Controls: controls services
- Admin Services → Backup Manager: manages backups
- API Client → Parser Entry: submits SQL
- Parser Entry → Parser Handler: handles request
- Parser Handler → SQL Generator: generates JSON
- Parser Handler → HTTP Response: formats errors