Architectural Diagrams

1. High-level Request Lifecycle

What happens when a request hits the server?

Client
  |
  | HTTP Request
  v
Gin Engine
  |
  |-- RateLimitMiddleware (Global)
  |
  |-- AuthMiddleware (Route Scoped)
  |
  |-- Handler
        |
        |-- Service
              |
              |-- Repository
                    |
                    |-- PostgreSQL

2. Authentication Architecture (JWT)

How authentication works internally?

Request
  |
  v
AuthMiddleware
  |
  |-- Extract Authorization Header
  |
  |-- JWTManager.ValidateToken()
        |
        |-- Verify Signature
        |-- Verify Expiry
        |-- Decode Claims
  |
  |-- user_id from Claims
  |
  |-- Inject into Gin Context
        c.Set("user_id")

3. Middleware Execution Order

In what order does middleware run?

Incoming Request
        |
        v
+----------------------+
| RateLimitMiddleware  |
+----------------------+
        |
        v
+----------------------+
| AuthMiddleware       |
+----------------------+
        |
        v
+----------------------+
| Handler              |
+----------------------+

4. Rate Limiting Design

How is rate limiting implemented safely?

Request
  |
  v
RateLimitMiddleware
  |
  |-- ClientIP()
  |
  |-- clients map
  |     IP → ClientLimiter
  |
  |-- rate.Limiter.Allow()
        |
        |-- ❌ Block → 429
        |-- ✅ Allow → Next

5. Dependency Injection & Composition

Where are dependencies created and injected?

app.BuildServer()
  |
  |-- JWTManager
  |
  |-- Repository
  |     |
  |     |-- PostgreSQL
  |
  |-- Service
  |
  |-- Handler
  |
  |-- Router
        |
        |-- Middleware
        |-- Handlers

Folder Structure

api-go
	|
	|-------> cmd/server
	|             |------> main.go
	|
	|
	|-------> internal 
	|             |
	|             |------> app
	|             |         |-----> app.go
	|             |    
	|             |------> auth
	|             |         |-----> jwt.go 
	|             |
	|             |
	|							|------> db
	|							|         |-----> postgres.go
	|							|
	|							|------> domain 
	|             |         |-----> errors.go
	|             |         |
	|             |         |-----> user.go
	|             |         |
	|							|         |-----> website.go
	|							|
	|							|------> dto
	|							|					|-----> websites.go
	|							|
	|							|------> handlers
	|							|					|-----> websites.go
	|             |
	|             |------> http
	|             |         |-----> apperror
	|							|         |          |-----------> mapper.go
	|             |         |
	|             |         |-----> context
	|             |         |          |-----------> context.go
	|             |         |
	|             |         |-----> middleware
	|             |         |          |-----------> auth.go
	|             |         |          |
	|             |         |          |-----------> rateLimit.go
	|             |         |     
	|             |         |
	|							|         |-----> response
	|							|                    |-----------> response.go 		
	|             |
	|							|
	|							|------> repository
	|							|         |-----> website_repository_pg.go
	|							|         |-----> website_repository.go
	|							|
	|							|
	|							|------> routes
	|							|					|-----> websites.go
	|             |         |
	|             |         |-----> health.go
	|             |         |
	|             |         |-----> router.go
	|							|
	|							|------> service
	|												|-----> websites.go		
	|
	|------> migrations
	|							|------> 20251226095007_create_websites_table.down.sql		
	|							|------> 20251226095007_create_websites_table.up.sql	
	|
	|------> .env	

Authentication

“Who is making the request ?”