# md-sufian-jidan/sportsync-api architecture

> Architecture diagram of the GitHub repository md-sufian-jidan/sportsync-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/md-sufian-jidan/sportsync-api
- Repository: https://github.com/md-sufian-jidan/sportsync-api

## Overview

1. **What this repo is**
   - SpotSync API is a Go backend for parking and EV charging reservations.
   - It is a REST API built on **Echo**, persists to **PostgreSQL** via **GORM**, and uses **JWT** for stateless authentication.

2. **Top-level runtime shape**
   - `cmd/main.go` is the application entry point.
   - Startup is mostly manual wiring: load config, open DB, build repositories/services/handlers, register routes, then start the Echo server.
   - `internal/server/http.go` is the HTTP composition point for middleware and route registration.

3. **Core architectural boundary**
   - The repo follows a layered, domain-oriented structure:
     - **Handler**: HTTP concerns only
     - **Service**: business rules and orchestration
     - **Repository**: database access only
     - **Entity/DTO**: data shapes for persistence and API contracts
   - Each domain keeps its own handler/service/repository/register files, which makes the diagram easier to draw as three vertical slices.

4. **Domain modules**
   - `internal/domain/user` covers registration, login, and profile lookup.
   - `internal/domain/admin` covers parking zone administration and likely admin-level oversight of reservations.
   - `internal/domain/reservations` covers booking, listing, and cancellation.
   - These domains are the main business subsystems and should be shown as peers, not as nested utilities.

5. **Request flow**
   - Incoming requests hit Echo routes in the server layer.
   - Handlers bind JSON into DTOs, validate inputs, and extract auth context when needed.
   - Services apply business rules and call repositories.
   - Repositories use GORM to read/write PostgreSQL.
   - Responses are normalized through `internal/httpResponse/response.go`.

6. **Authentication and authorization**
   - `internal/auth/jwt.go` is responsible for generating and validating JWTs.
   - `internal/middleware/checkAuth.go` enforces protected routes and role checks.
   - The repo distinguishes at least two roles: **driver** and **admin**.
   - Auth is a cross-cutting concern that sits beside the domain modules, not inside them.

7. **Reservation integrity and concurrency**
   - The reservation flow is the most critical business path.
   - The README indicates the repository uses **database transactions** and **row-level locks (`FOR UPDATE`)** to prevent double-booking the last spot.
   - This means the repository layer is not just CRUD; it owns the concurrency boundary that guarantees capacity correctness.

8. **Data model and relationships**
   - PostgreSQL stores three main tables: `users`, `parking_zones`, and `reservations`.
   - `reservations` links a user to a parking zone, with status tracking for active/cancelled/completed states.
   - Zone availability is computed dynamically from total capacity minus active reservations, so availability is derived data rather than a stored source of truth.

9. **DTOs and response shaping**
   - Each domain has a `dto/` package for request and response models.
   - DTOs prevent the API from exposing GORM entities directly.
   - This boundary is important for architecture diagrams because it separates external API contracts from internal persistence models.

10. **Shared HTTP and error handling**
   - `internal/httpResponse` centralizes success/error envelope formatting.
   - The README emphasizes that raw ORM errors are not returned to clients.
   - That makes error handling a shared concern across all handlers, with consistent JSON responses and HTTP status codes.

11. **Documentation and discoverability**
   - `docs/swagger.yaml`, `docs/swagger.json`, and `docs/docs.go` show Swagger is generated into the repo.
   - Swagger UI is part of the runtime surface, so it should be drawn as a documentation endpoint hanging off the HTTP server.

12. **Configuration and environment**
   - `internal/config` loads environment values and constructs the DB connection.
   - The repo depends on runtime configuration for port, DB credentials, SSL mode, and JWT secret.
   - `.env.example` and `.air.toml` indicate local development support with hot reload, but they do not change the production architecture.

13. **Deployment context**
   - The README shows deployment on **Render** with **NeonDB/Supabase-like PostgreSQL**.
   - Architecture-wise, the app is a stateless API server with an external managed database.
   - No separate message broker, cache, or background worker appears in the tree.

14. **What to emphasize in a diagram**
   - Show a single HTTP server feeding three business domains.
   - Show auth/middleware as cross-cutting controls around protected routes.
   - Show repositories as the only path to PostgreSQL.
   - Highlight the reservation transaction/lock path as the main consistency-critical flow.

Main entry points: [`internal/server/http.go`](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/server/http.go) (HTTP server), [`cmd/main.go`](https://github.com/md-sufian-jidan/sportsync-api/blob/main/cmd/main.go) (main), [`internal/domain/user/handler.go`](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/handler.go) (User API), [`internal/domain/admin/handler.go`](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/handler.go) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_cmd_main(("main<br/>entrypoint<br/>[main.go]"))
  node_server_http["HTTP server<br/>echo composition<br/>[http.go]"]
  node_config_app["Config<br/>[config.go]"]
  node_config_db[("DB config<br/>gorm setup<br/>[db.go]")]
end

subgraph group_crosscutting["Cross-cutting"]
  node_jwt_auth{{"JWT<br/>token auth<br/>[jwt.go]"}}
  node_auth_mw{{"Auth guard<br/>middleware<br/>[checkAuth.go]"}}
  node_http_resp["Responses<br/>http envelope<br/>[response.go]"]
end

subgraph group_domains["Domains"]
  node_user_handler["User API<br/>handler<br/>[handler.go]"]
  node_user_service["User logic<br/>[service.go]"]
  node_user_repo[("User store<br/>[repository.go]")]
  node_admin_handler["Admin API<br/>handler<br/>[handler.go]"]
  node_admin_service["Admin logic<br/>[service.go]"]
  node_admin_repo[("Admin store<br/>[repository.go]")]
  node_res_handler["Reserve API<br/>handler<br/>[handler.go]"]
  node_res_service["Reserve logic<br/>[service.go]"]
  node_res_repo[("Reserve store<br/>[repository.go]")]
end

subgraph group_docs["Docs"]
  node_docs_api["Swagger<br/>generated docs<br/>[swagger.yaml]"]
end

subgraph group_infra["Infrastructure"]
  node_postgres[("PostgreSQL<br/>external db")]
end

node_cmd_main -->|"load"| node_config_app
node_cmd_main -->|"connect"| node_config_db
node_cmd_main -->|"start"| node_server_http
node_server_http -->|"middleware"| node_auth_mw
node_server_http -->|"routes"| node_user_handler
node_server_http -->|"routes"| node_admin_handler
node_server_http -->|"routes"| node_res_handler
node_server_http -->|"docs"| node_docs_api
node_auth_mw -->|"validate"| node_jwt_auth
node_user_handler -->|"call"| node_user_service
node_user_handler -->|"shape"| node_http_resp
node_user_service -->|"persist"| node_user_repo
node_user_repo -->|"sql"| node_postgres
node_admin_handler -->|"call"| node_admin_service
node_admin_handler -->|"shape"| node_http_resp
node_admin_service -->|"persist"| node_admin_repo
node_admin_repo -->|"sql"| node_postgres
node_res_handler -->|"call"| node_res_service
node_res_handler -->|"shape"| node_http_resp
node_res_service -->|"transact"| node_res_repo
node_res_repo -->|"lock"| node_postgres
node_res_service -.->|"claims"| node_jwt_auth
node_config_app -->|"db settings"| node_config_db

click node_cmd_main "https://github.com/md-sufian-jidan/sportsync-api/blob/main/cmd/main.go"
click node_server_http "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/server/http.go"
click node_config_app "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/config/config.go"
click node_config_db "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/config/db.go"
click node_jwt_auth "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/auth/jwt.go"
click node_auth_mw "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/middleware/checkAuth.go"
click node_http_resp "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/httpResponse/response.go"
click node_user_handler "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/handler.go"
click node_user_service "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/service.go"
click node_user_repo "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/repository.go"
click node_admin_handler "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/handler.go"
click node_admin_service "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/service.go"
click node_admin_repo "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/repository.go"
click node_res_handler "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/handler.go"
click node_res_service "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/service.go"
click node_res_repo "https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/repository.go"
click node_docs_api "https://github.com/md-sufian-jidan/sportsync-api/blob/main/docs/swagger.yaml"

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_cmd_main,node_server_http,node_config_app,node_config_db toneBlue
class node_jwt_auth,node_auth_mw,node_http_resp toneAmber
class node_user_handler,node_user_service,node_user_repo,node_admin_handler,node_admin_service,node_admin_repo,node_res_handler,node_res_service,node_res_repo toneMint
class node_docs_api toneRose
class node_postgres toneIndigo
```

## Components

### Bootstrap

Process startup, config, and server composition.

- [main](https://github.com/md-sufian-jidan/sportsync-api/blob/main/cmd/main.go): entrypoint · Application entrypoint that wires config, database, routes, and server startup. · `cmd/main.go`
- [HTTP server](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/server/http.go): echo composition · Registers middleware and routes around the Echo HTTP runtime. · `internal/server/http.go`
- [Config](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/config/config.go): env config · Loads runtime settings such as port, DB credentials, SSL mode, and JWT secret. · `internal/config/config.go`
- [DB config](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/config/db.go): gorm setup · Builds the PostgreSQL connection used by repositories. · `internal/config/db.go`

### Cross-cutting

Authentication, middleware, and shared HTTP response shaping.

- [JWT](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/auth/jwt.go): token auth · Generates and validates stateless authentication tokens. · `internal/auth/jwt.go`
- [Auth guard](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/middleware/checkAuth.go): middleware · Protects routes and enforces role checks for driver and admin access. · `internal/middleware/checkAuth.go`
- [Responses](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/httpResponse/response.go): http envelope · Normalizes success and error payloads returned by handlers. · `internal/httpResponse/response.go`

### Domains

Business slices for users, admins, and reservations.

- [User API](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/handler.go): handler · Handles registration, login, and profile lookup requests. · `internal/domain/user/handler.go`
- [User logic](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/service.go): service · Applies user business rules and orchestrates repository calls. · `internal/domain/user/service.go`
- [User store](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/user/repository.go): repository · Persists and loads user records from PostgreSQL. · `internal/domain/user/repository.go`
- [Admin API](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/handler.go): handler · Handles parking zone administration and oversight actions. · `internal/domain/admin/handler.go`
- [Admin logic](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/service.go): service · Coordinates admin workflows and business rules. · `internal/domain/admin/service.go`
- [Admin store](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/admin/repository.go): repository · Accesses parking zone and admin-related persistence. · `internal/domain/admin/repository.go`
- [Reserve API](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/handler.go): handler · Handles booking, listing, and cancellation requests. · `internal/domain/reservations/handler.go`
- [Reserve logic](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/service.go): service · Coordinates reservation rules and availability checks. · `internal/domain/reservations/service.go`
- [Reserve store](https://github.com/md-sufian-jidan/sportsync-api/blob/main/internal/domain/reservations/repository.go): repository · Persists reservations and enforces transactional capacity consistency. · `internal/domain/reservations/repository.go`

### Docs

Generated API documentation surface.

- [Swagger](https://github.com/md-sufian-jidan/sportsync-api/blob/main/docs/swagger.yaml): generated docs · Generated OpenAPI/Swagger documentation exposed alongside the HTTP API. · `docs/swagger.yaml`

### Infrastructure

External persistence backend.

- **PostgreSQL**: external db · Managed relational database backing users, zones, and reservations.

## Connections

- main → Config: load · Startup reads runtime configuration.
- main → DB config: connect · Startup opens the database connection.
- main → HTTP server: start · Main hands off to the HTTP server composition.
- HTTP server → Auth guard: middleware · Server installs authentication and role guards.
- HTTP server → User API: routes · Registers user endpoints.
- HTTP server → Admin API: routes · Registers admin endpoints.
- HTTP server → Reserve API: routes · Registers reservation endpoints.
- HTTP server → Swagger: docs · Exposes generated API documentation.
- Auth guard → JWT: validate · Middleware validates bearer tokens and claims.
- User API → User logic: call · HTTP layer delegates to business logic.
- User API → Responses: shape · Handlers normalize responses through the shared envelope.
- User logic → User store: persist · User rules use repository access.
- User store → PostgreSQL: sql · Repository reads and writes PostgreSQL.
- Admin API → Admin logic: call · HTTP layer delegates admin workflows.
- Admin API → Responses: shape · Handlers normalize responses through the shared envelope.
- Admin logic → Admin store: persist · Admin logic uses repository access.
- Admin store → PostgreSQL: sql · Repository reads and writes PostgreSQL.
- Reserve API → Reserve logic: call · HTTP layer delegates reservation workflows.
- Reserve API → Responses: shape · Handlers normalize responses through the shared envelope.
- Reserve logic → Reserve store: transact · Reservation logic relies on transactional store operations.
- Reserve store → PostgreSQL: lock · Repository uses transactions and row locks to prevent double booking.
- Reserve logic → JWT: claims · Reservation flows may rely on authenticated identity.
- Config → DB config: db settings · Config feeds database setup.