How md-sufian-jidan/sportsync-api works
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: http.go HTTP server · main.go main · user/handler.go User API · admin/handler.go Admin API
Components 18
Bootstrap
Process startup, config, and server composition.
- main · Application entrypoint that wires config, database, routes, and server startup.
cmd/main.go - HTTP server · Registers middleware and routes around the Echo HTTP runtime.
internal/server/http.go - Config · Loads runtime settings such as port, DB credentials, SSL mode, and JWT secret.
internal/config/config.go - DB config · Builds the PostgreSQL connection used by repositories.
internal/config/db.go
Cross-cutting
Authentication, middleware, and shared HTTP response shaping.
- JWT · Generates and validates stateless authentication tokens.
internal/auth/jwt.go - Auth guard · Protects routes and enforces role checks for driver and admin access.
internal/middleware/checkAuth.go - Responses · Normalizes success and error payloads returned by handlers.
internal/httpResponse/response.go
Domains
Business slices for users, admins, and reservations.
- User API · Handles registration, login, and profile lookup requests.
internal/domain/user/handler.go - User logic · Applies user business rules and orchestrates repository calls.
internal/domain/user/service.go - User store · Persists and loads user records from PostgreSQL.
internal/domain/user/repository.go - Admin API · Handles parking zone administration and oversight actions.
internal/domain/admin/handler.go - Admin logic · Coordinates admin workflows and business rules.
internal/domain/admin/service.go - Admin store · Accesses parking zone and admin-related persistence.
internal/domain/admin/repository.go - Reserve API · Handles booking, listing, and cancellation requests.
internal/domain/reservations/handler.go - Reserve logic · Coordinates reservation rules and availability checks.
internal/domain/reservations/service.go - Reserve store · Persists reservations and enforces transactional capacity consistency.
internal/domain/reservations/repository.go
Docs
Generated API documentation surface.
- Swagger · Generated OpenAPI/Swagger documentation exposed alongside the HTTP API.
docs/swagger.yaml
Infrastructure
External persistence backend.
- PostgreSQL · Managed relational database backing users, zones, and reservations.
Connections 23
- 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.