# rostyslav452/keyboardbuilderapi architecture

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

- Interactive diagram: https://gitdiagram.com/rostyslav452/keyboardbuilderapi
- Repository: https://github.com/rostyslav452/keyboardbuilderapi

## Overview

This is a REST API for authenticating users, managing mechanical-keyboard parts, and creating user-owned builds. The main workflow is an HTTP request through Express routing and validation to a controller, then a domain service and Sequelize models backed by MySQL; build operations combine a user’s selected switch, case, PCB, and keycaps. Authentication additionally issues and rotates JWTs while persisting refresh tokens. The README documents security, logging, pagination, and health-check capabilities; some route and middleware wiring is represented from documentation because those implementations were not sampled.

Main entry points: [`src/models/index.ts`](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/index.ts) (Sequelize models), [`src/app.ts`](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/app.ts) (Express app), [`src/routers`](https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/routers) (API routers), [`src/services/auth.service.ts`](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/auth.service.ts) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP handling"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["Express app<br/>[app.ts]"]
  node_routers["API routers"]
  node_validation["Validated handler"]
  node_schemas["Request schemas"]
  node_errors["Error handling<br/>[errorHandler.ts]"]
  node_logger["Request logging<br/>[requestLogger.ts]"]
  node_health["Health endpoint<br/>[app.ts]"]
end

subgraph group_identity["Identity and security"]
  node_request_security["Request security"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_jwt["JWT utilities<br/>[jwt.util.ts]"]
  node_auth_schema["Auth schemas<br/>[auth.schema.ts]"]
end

subgraph group_domain["Parts and builds"]
  node_parts_controller["Parts controller"]
  node_parts_service["Parts service<br/>[part.service.ts]"]
  node_part_schema["Part schemas<br/>[part.schema.ts]"]
  node_build_controller["Build controller"]
  node_build_service["Build service<br/>[build.service.ts]"]
  node_build_schema["Build schemas<br/>[build.schema.ts]"]
end

subgraph group_data["Persistence"]
  node_models["Sequelize models<br/>[index.ts]"]
  node_user_model["Users and tokens<br/>[user.model.ts]"]
  node_part_model["Keyboard parts<br/>[part.model.ts]"]
  node_build_model["Keyboard builds<br/>[build.model.ts]"]
end

node_client(("API client"))
node_database[("MySQL database")]

node_client -->|"sends requests"| node_server
node_server -->|"serves"| node_app
node_server -->|"authenticates connection"| node_database
node_app -->|"mounts routes"| node_routers
node_app -->|"serves health check"| node_health
node_app -->|"applies middleware"| node_request_security
node_app -->|"logs requests"| node_logger
node_app -->|"handles errors"| node_errors
node_routers -->|"dispatches auth"| node_auth_controller
node_routers -->|"dispatches parts"| node_parts_controller
node_routers -->|"dispatches builds"| node_build_controller
node_routers -->|"protects private routes"| node_request_security
node_auth_controller -->|"wraps handlers"| node_validation
node_parts_controller -->|"wraps handlers"| node_validation
node_build_controller -->|"wraps handlers"| node_validation
node_validation -->|"parses requests"| node_schemas
node_auth_controller -->|"validates auth input"| node_auth_schema
node_parts_controller -->|"validates part input"| node_part_schema
node_build_controller -->|"validates build input"| node_build_schema
node_auth_controller -->|"invokes auth"| node_auth_service
node_parts_controller -->|"invokes parts"| node_parts_service
node_build_controller -->|"invokes builds"| node_build_service
node_auth_service -->|"reads and writes"| node_models
node_parts_service -->|"reads and writes"| node_models
node_build_service -->|"reads and writes"| node_models
node_auth_service -->|"signs and verifies"| node_jwt
node_request_security -->|"validates access tokens"| node_jwt
node_models -->|"initializes"| node_user_model
node_models -->|"initializes"| node_part_model
node_models -->|"initializes"| node_build_model
node_models -->|"queries via Sequelize"| node_database
node_auth_service -->|"uses user records"| node_user_model
node_auth_service -->|"stores refresh tokens"| node_user_model
node_build_service -->|"loads build components"| node_part_model

click node_server "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/server.ts"
click node_app "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/app.ts"
click node_routers "https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/routers"
click node_validation "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/utils/createValidatedHandler.ts"
click node_schemas "https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/schemas"
click node_errors "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/middlewares/errorHandler.ts"
click node_request_security "https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/middlewares"
click node_auth_controller "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/auth.controller.ts"
click node_auth_service "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/auth.service.ts"
click node_jwt "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/utils/jwt.util.ts"
click node_auth_schema "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/auth.schema.ts"
click node_parts_controller "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/parts.controller.ts"
click node_parts_service "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/part.service.ts"
click node_part_schema "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/part.schema.ts"
click node_build_controller "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/builds.controller.ts"
click node_build_service "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/build.service.ts"
click node_build_schema "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/build.schema.ts"
click node_models "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/index.ts"
click node_user_model "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/user.model.ts"
click node_part_model "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/part.model.ts"
click node_build_model "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/build.model.ts"
click node_logger "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/middlewares/requestLogger.ts"
click node_health "https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/app.ts"

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_server,node_app,node_routers,node_validation,node_schemas,node_errors,node_logger,node_health,node_client toneBlue
class node_request_security,node_auth_controller,node_auth_service,node_jwt,node_auth_schema,node_database toneAmber
class node_parts_controller,node_parts_service,node_part_schema,node_build_controller,node_build_service,node_build_schema toneMint
class node_models,node_user_model,node_part_model,node_build_model toneRose
```

## Components

### HTTP handling

- [HTTP server](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/server.ts): `src/server.ts`
- [Express app](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/app.ts): `src/app.ts`
- [API routers](https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/routers): `src/routers`
- [Validated handler](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/utils/createValidatedHandler.ts): `src/utils/createValidatedHandler.ts`
- [Request schemas](https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/schemas): `src/schemas`
- [Error handling](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/middlewares/errorHandler.ts): `src/middlewares/errorHandler.ts`
- [Request logging](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/middlewares/requestLogger.ts): `src/middlewares/requestLogger.ts`
- [Health endpoint](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/app.ts): `src/app.ts`

### Identity and security

- [Request security](https://github.com/rostyslav452/keyboardbuilderapi/tree/master/src/middlewares): `src/middlewares`
- [Auth controller](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/auth.controller.ts): `src/controllers/auth.controller.ts`
- [Auth service](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/auth.service.ts): `src/services/auth.service.ts`
- [JWT utilities](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/utils/jwt.util.ts): `src/utils/jwt.util.ts`
- [Auth schemas](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/auth.schema.ts): `src/schemas/auth.schema.ts`

### Parts and builds

- [Parts controller](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/parts.controller.ts): `src/controllers/parts.controller.ts`
- [Parts service](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/part.service.ts): `src/services/part.service.ts`
- [Part schemas](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/part.schema.ts): `src/schemas/part.schema.ts`
- [Build controller](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/controllers/builds.controller.ts): `src/controllers/builds.controller.ts`
- [Build service](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/services/build.service.ts): `src/services/build.service.ts`
- [Build schemas](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/schemas/build.schema.ts): `src/schemas/build.schema.ts`

### Persistence

- [Sequelize models](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/index.ts): `src/models/index.ts`
- [Users and tokens](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/user.model.ts): `src/models/user.model.ts`
- [Keyboard parts](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/part.model.ts): `src/models/part.model.ts`
- [Keyboard builds](https://github.com/rostyslav452/keyboardbuilderapi/blob/master/src/models/build.model.ts): `src/models/build.model.ts`

### Other components

- **API client**
- **MySQL database**

## Connections

- API client → HTTP server: sends requests
- HTTP server → Express app: serves
- HTTP server → MySQL database: authenticates connection
- Express app → API routers: mounts routes
- Express app → Health endpoint: serves health check
- Express app → Request security: applies middleware
- Express app → Request logging: logs requests
- Express app → Error handling: handles errors
- API routers → Auth controller: dispatches auth
- API routers → Parts controller: dispatches parts
- API routers → Build controller: dispatches builds
- API routers → Request security: protects private routes
- Auth controller → Validated handler: wraps handlers
- Parts controller → Validated handler: wraps handlers
- Build controller → Validated handler: wraps handlers
- Validated handler → Request schemas: parses requests
- Auth controller → Auth schemas: validates auth input
- Parts controller → Part schemas: validates part input
- Build controller → Build schemas: validates build input
- Auth controller → Auth service: invokes auth
- Parts controller → Parts service: invokes parts
- Build controller → Build service: invokes builds
- Auth service → Sequelize models: reads and writes
- Parts service → Sequelize models: reads and writes
- Build service → Sequelize models: reads and writes
- Auth service → JWT utilities: signs and verifies
- Request security → JWT utilities: validates access tokens
- Sequelize models → Users and tokens: initializes
- Sequelize models → Keyboard parts: initializes
- Sequelize models → Keyboard builds: initializes
- Sequelize models → MySQL database: queries via Sequelize
- Auth service → Users and tokens: uses user records
- Auth service → Users and tokens: stores refresh tokens
- Build service → Keyboard parts: loads build components