diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..b2e74e2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,71 @@
+# Documentação - Go Cart API
+
+Bem-vindo à documentação técnica do projeto Go Cart API. Este diretório contém toda a documentação arquitetural e técnica do sistema.
+
+## 📁 Arquivos de Documentação
+
+### 🏗️ [architecture.md](./architecture.md)
+Documentação completa da arquitetura do sistema, incluindo:
+
+- **Diagrama de Arquitetura Geral**: Visão macro do sistema com todas as camadas
+- **Fluxo de Autenticação**: Sequência detalhada dos processos de login/registro
+- **Modelo de Dados (ERD)**: Estrutura do banco de dados com relacionamentos
+- **Fluxo de Requests**: Como as requisições são processadas
+- **Estrutura de Pastas**: Organização do código e responsabilidades
+- **Tecnologias Utilizadas**: Stack tecnológico completo
+- **Padrões Arquiteturais**: Design patterns implementados
+
+## 🎯 Como Visualizar os Diagramas
+
+Os diagramas estão criados em formato **Mermaid**, que pode ser visualizado em:
+
+### GitHub
+Os diagramas são renderizados automaticamente quando você visualiza os arquivos `.md` diretamente no GitHub.
+
+### Editores Locais
+- **VS Code**: Instale a extensão "Mermaid Preview"
+- **IntelliJ/GoLand**: Suporte nativo para Mermaid
+- **Online**: [Mermaid Live Editor](https://mermaid.live/)
+
+### Documentação Online
+- GitBook, Notion, ou qualquer plataforma que suporte Mermaid
+
+## 🧩 Visão Geral da Arquitetura
+
+Este projeto segue os princípios de **Clean Architecture** com as seguintes características:
+
+- **Separação de Responsabilidades**: Cada camada tem função específica
+- **Inversão de Dependências**: Interfaces bem definidas entre camadas  
+- **Testabilidade**: Estrutura preparada para testes unitários e integração
+- **Escalabilidade**: Arquitetura que facilita crescimento e manutenção
+
+## 🚀 Stack Tecnológico Principal
+
+- **Backend**: Go 1.23+ com Gorilla Mux
+- **Database**: PostgreSQL via Supabase
+- **Autenticação**: JWT + bcrypt
+- **Deploy**: Render/Heroku
+- **Testes**: Go testing + testify
+
+## 📚 Para Desenvolvedores
+
+Se você é novo no projeto, recomendamos a leitura na seguinte ordem:
+
+1. **README principal** do projeto para setup inicial
+2. **[architecture.md](./architecture.md)** para entender a estrutura
+3. **Código fonte** começando por `cmd/main.go`
+4. **Testes** em `internal/handlers/*_test.go`
+
+## 🔄 Manutenção da Documentação
+
+Esta documentação deve ser atualizada sempre que:
+- Novos componentes forem adicionados
+- A arquitetura for modificada
+- Novas dependências forem incluídas
+- Padrões de desenvolvimento mudarem
+
+## 📞 Suporte
+
+Para dúvidas sobre a arquitetura ou documentação:
+- Abra uma issue no repositório
+- Entre em contato com a equipe de desenvolvimento
\ No newline at end of file
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..8c9e36f
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,426 @@
+# Diagrama de Arquitetura - Go Cart API
+
+Esta documentação apresenta os diagramas de arquitetura do sistema Go Cart API, uma API RESTful em Go para e-commerce.
+
+## 1. Arquitetura Geral do Sistema
+
+```mermaid
+graph TB
+    subgraph "Cliente"
+        Client[Cliente HTTP/API]
+        WebApp[Aplicação Web]
+        Mobile[App Mobile]
+    end
+
+    subgraph "Load Balancer/Reverse Proxy"
+        LB[Load Balancer<br/>Nginx/Render]
+    end
+
+    subgraph "Go Cart API Application"
+        subgraph "HTTP Layer"
+            Router[Gorilla Mux Router<br/>:4445+]
+            MW[Auth Middleware<br/>JWT Validation]
+        end
+
+        subgraph "Handler Layer"
+            AuthH[Auth Handler<br/>Login/Register]
+            UserH[User Handler<br/>Profile/Addresses]
+            ProductH[Product Handler<br/>CRUD Products]
+            CategoryH[Category Handler<br/>CRUD Categories]
+            CartH[Cart Handler<br/>Shopping Cart]
+            OrderH[Order Handler<br/>Order Management]
+            HealthH[Health Handler<br/>System Status]
+        end
+
+        subgraph "Business Logic Layer"
+            UserRepo[User Repository]
+            ProductRepo[Product Repository]
+            CategoryRepo[Category Repository]
+            AddressRepo[Address Repository]
+            CartRepo[Cart Repository]
+            OrderRepo[Order Repository]
+        end
+
+        subgraph "Security & Utils"
+            JWT[JWT Service<br/>Token Generation]
+            BCrypt[BCrypt Hasher<br/>Password Security]
+            WebUtils[Web Utils<br/>JSON Helpers]
+        end
+
+        subgraph "Configuration"
+            Config[Config Loader<br/>ENV Variables]
+            DB[Database Connection<br/>pgxpool]
+        end
+    end
+
+    subgraph "External Services"
+        subgraph "Database"
+            PostgreSQL[(PostgreSQL<br/>via Supabase)]
+        end
+        
+        subgraph "Environment"
+            ENV[Environment Variables<br/>DATABASE_URL<br/>JWT_SECRET<br/>PORT]
+        end
+    end
+
+    %% Connections
+    Client --> LB
+    WebApp --> LB
+    Mobile --> LB
+    
+    LB --> Router
+    
+    Router --> MW
+    MW --> AuthH
+    MW --> UserH
+    MW --> ProductH
+    MW --> CategoryH
+    MW --> CartH
+    MW --> OrderH
+    Router --> HealthH
+    
+    AuthH --> UserRepo
+    AuthH --> JWT
+    AuthH --> BCrypt
+    
+    UserH --> UserRepo
+    UserH --> AddressRepo
+    
+    ProductH --> ProductRepo
+    CategoryH --> CategoryRepo
+    CartH --> CartRepo
+    CartH --> ProductRepo
+    OrderH --> OrderRepo
+    OrderH --> CartRepo
+    OrderH --> AddressRepo
+    
+    UserRepo --> DB
+    ProductRepo --> DB
+    CategoryRepo --> DB
+    AddressRepo --> DB
+    CartRepo --> DB
+    OrderRepo --> DB
+    
+    DB --> PostgreSQL
+    Config --> ENV
+    
+    %% Styling
+    classDef handler fill:#e1f5fe
+    classDef repo fill:#f3e5f5
+    classDef security fill:#fff3e0
+    classDef database fill:#e8f5e8
+    classDef external fill:#fce4ec
+    
+    class AuthH,UserH,ProductH,CategoryH,CartH,OrderH,HealthH handler
+    class UserRepo,ProductRepo,CategoryRepo,AddressRepo,CartRepo,OrderRepo repo
+    class JWT,BCrypt,MW security
+    class PostgreSQL,DB database
+    class ENV,LB external
+```
+
+## 2. Fluxo de Autenticação
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as Router
+    participant AH as Auth Handler
+    participant UR as User Repository
+    participant BC as BCrypt
+    participant JWT as JWT Service
+    participant DB as PostgreSQL
+
+    %% Registro
+    Note over C,DB: Fluxo de Registro
+    C->>+R: POST /api/auth/register
+    R->>+AH: Register()
+    AH->>+BC: HashPassword()
+    BC-->>-AH: hashedPassword
+    AH->>+UR: Create(name, email, hash)
+    UR->>+DB: INSERT INTO users
+    DB-->>-UR: user created
+    UR-->>-AH: User object
+    AH->>+JWT: GenerateToken(userID)
+    JWT-->>-AH: token
+    AH-->>-R: {user, token}
+    R-->>-C: 201 Created
+
+    %% Login
+    Note over C,DB: Fluxo de Login
+    C->>+R: POST /api/auth/login
+    R->>+AH: Login()
+    AH->>+UR: FindByEmail(email)
+    UR->>+DB: SELECT FROM users
+    DB-->>-UR: user data
+    UR-->>-AH: User object
+    AH->>+BC: ValidatePassword()
+    BC-->>-AH: valid/invalid
+    AH->>+JWT: GenerateToken(userID)
+    JWT-->>-AH: token
+    AH-->>-R: {user, token}
+    R-->>-C: 200 OK
+
+    %% Autenticação
+    Note over C,DB: Requests Autenticados
+    C->>+R: GET /api/users/me (Bearer token)
+    R->>+MW: Authenticate()
+    MW->>+JWT: ValidateToken()
+    JWT-->>-MW: claims
+    MW->>+UR: FindByID(userID)
+    UR-->>-MW: user exists
+    MW-->>-R: context with userID
+    R->>UH: GetMe()
+    UH-->>R: user data
+    R-->>-C: 200 OK
+```
+
+## 3. Modelo de Dados (ERD)
+
+```mermaid
+erDiagram
+    USERS {
+        uuid id PK
+        string name
+        string email UK
+        string password_hash
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    ADDRESSES {
+        uuid id PK
+        uuid user_id FK
+        string street
+        string city
+        string state
+        string zip_code
+        string country
+        boolean is_default
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    CATEGORIES {
+        uuid id PK
+        string name UK
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    PRODUCTS {
+        uuid id PK
+        string name
+        string description
+        decimal price
+        uuid category_id FK "nullable"
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    CARTS {
+        uuid id PK
+        uuid user_id FK
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    CART_ITEMS {
+        uuid id PK
+        uuid cart_id FK
+        uuid product_id FK
+        integer quantity
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    ORDERS {
+        uuid id PK
+        uuid user_id FK
+        uuid address_id FK
+        decimal total_amount
+        string status
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    ORDER_ITEMS {
+        uuid id PK
+        uuid order_id FK
+        uuid product_id FK
+        integer quantity
+        decimal price_at_time
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    %% Relationships
+    USERS ||--o{ ADDRESSES : "has"
+    USERS ||--|| CARTS : "owns"
+    USERS ||--o{ ORDERS : "places"
+    
+    CATEGORIES ||--o{ PRODUCTS : "contains"
+    
+    CARTS ||--o{ CART_ITEMS : "contains"
+    PRODUCTS ||--o{ CART_ITEMS : "referenced_by"
+    
+    ORDERS ||--o{ ORDER_ITEMS : "contains"
+    PRODUCTS ||--o{ ORDER_ITEMS : "referenced_by"
+    ADDRESSES ||--o{ ORDERS : "delivery_to"
+```
+
+## 4. Fluxo de API Requests
+
+```mermaid
+graph TD
+    A[Cliente HTTP Request] --> B{Rota Pública?}
+    
+    B -->|Sim| C[Handler Direto]
+    B -->|Não| D[Auth Middleware]
+    
+    D --> E{Token Válido?}
+    E -->|Não| F[401 Unauthorized]
+    E -->|Sim| G[Adicionar UserID ao Context]
+    
+    G --> H[Handler Específico]
+    C --> H
+    
+    H --> I[Validar Request]
+    I --> J{Dados Válidos?}
+    J -->|Não| K[400 Bad Request]
+    J -->|Sim| L[Repository Layer]
+    
+    L --> M[Database Query]
+    M --> N{Query Sucesso?}
+    N -->|Não| O[500 Internal Error]
+    N -->|Sim| P[Processar Resultado]
+    
+    P --> Q[JSON Response]
+    Q --> R[Cliente]
+    
+    F --> R
+    K --> R
+    O --> R
+    
+    %% Styling
+    classDef error fill:#ffcdd2
+    classDef success fill:#c8e6c9
+    classDef process fill:#e1f5fe
+    
+    class F,K,O error
+    class Q,R success
+    class D,G,H,I,L,P process
+```
+
+## 5. Estrutura de Pastas e Responsabilidades
+
+```mermaid
+graph TD
+    subgraph "Projeto Go Cart API"
+        subgraph "cmd/"
+            MainGo[main.go<br/>• Entry point<br/>• Server setup<br/>• Route configuration]
+        end
+        
+        subgraph "internal/"
+            subgraph "handlers/"
+                Handlers[• HTTP request handling<br/>• Input validation<br/>• Response formatting<br/>• Error handling]
+            end
+            
+            subgraph "models/"
+                Models[• Data structures<br/>• Business entities<br/>• JSON tags<br/>• Database mappings]
+            end
+            
+            subgraph "repositories/"
+                Repos[users/<br/>products/<br/>categories/<br/>addresses/<br/>cart/<br/>orders/<br/>• Database operations<br/>• Query implementation<br/>• Error handling]
+            end
+            
+            subgraph "auth/"
+                Auth[• JWT handling<br/>• Password hashing<br/>• Middleware<br/>• Authentication logic]
+            end
+            
+            subgraph "config/"
+                Config[• Environment variables<br/>• Configuration loading<br/>• Application settings]
+            end
+            
+            subgraph "database/"
+                Database[• Connection management<br/>• Pool configuration<br/>• Migration handling]
+            end
+            
+            subgraph "webutils/"
+                WebUtils[• JSON helpers<br/>• HTTP utilities<br/>• Common functions]
+            end
+        end
+        
+        subgraph "docs/"
+            Docs[• API documentation<br/>• Architecture diagrams<br/>• Usage examples]
+        end
+    end
+    
+    MainGo --> Handlers
+    MainGo --> Config
+    MainGo --> Database
+    
+    Handlers --> Models
+    Handlers --> Repos
+    Handlers --> Auth
+    Handlers --> WebUtils
+    
+    Repos --> Models
+    Repos --> Database
+    
+    Auth --> Repos
+    
+    %% Styling
+    classDef entry fill:#fff3e0
+    classDef business fill:#e8f5e8
+    classDef data fill:#e1f5fe
+    classDef security fill:#fce4ec
+    classDef config fill:#f3e5f5
+    
+    class MainGo entry
+    class Handlers,Models business
+    class Repos,Database data
+    class Auth security
+    class Config,WebUtils,Docs config
+```
+
+## 6. Tecnologias e Dependências
+
+### Core Dependencies
+- **Go 1.23+**: Linguagem principal
+- **Gorilla Mux**: Roteamento HTTP
+- **pgx/v5**: Driver PostgreSQL
+- **UUID**: Identificadores únicos
+- **JWT**: Autenticação baseada em tokens
+- **bcrypt**: Hash de senhas
+
+### External Services
+- **PostgreSQL**: Banco de dados principal (via Supabase)
+- **Render/Heroku**: Hospedagem da aplicação
+
+### Environment Variables
+- `DATABASE_URL`: Connection string do PostgreSQL
+- `JWT_SECRET`: Chave secreta para tokens JWT
+- `PORT`: Porta do servidor (auto-detectada se não definida)
+
+## 7. Padrões Arquiteturais
+
+### Clean Architecture
+- **Separation of Concerns**: Cada camada tem responsabilidade específica
+- **Dependency Inversion**: Repositories como interfaces, implementações injetadas
+- **Independence**: Regras de negócio independentes de frameworks
+
+### Repository Pattern
+- Abstração do acesso a dados
+- Interfaces para testabilidade
+- Implementações específicas para PostgreSQL
+
+### Middleware Pattern
+- Autenticação centralizada
+- Interceptação de requests
+- Context enrichment
+
+### RESTful API Design
+- Recursos bem definidos
+- Métodos HTTP semânticos
+- Status codes apropriados
+- JSON como formato padrão
\ No newline at end of file
diff --git a/docs/endpoints.md b/docs/endpoints.md
new file mode 100644
index 0000000..2b0bcee
--- /dev/null
+++ b/docs/endpoints.md
@@ -0,0 +1,102 @@
+# API Endpoints Overview - Go Cart API
+
+## 🗺️ Mapa de Endpoints
+
+```mermaid
+graph LR
+    subgraph "Rotas Públicas"
+        A[GET /api/health]
+        B[POST /api/auth/register]
+        C[POST /api/auth/login]
+        D[GET /api/products]
+        E[GET /api/products/{id}]
+        F[GET /api/categories]
+        G[GET /api/categories/{id}]
+    end
+    
+    subgraph "Rotas Protegidas 🔒"
+        subgraph "Users"
+            H[GET /api/users/me]
+            I[GET /api/users/{id}/addresses]
+            J[POST /api/users/{id}/addresses]
+            K[PUT /api/users/{id}/addresses/{aid}]
+            L[DELETE /api/users/{id}/addresses/{aid}]
+            M[PATCH /api/users/{id}/addresses/{aid}/default]
+        end
+        
+        subgraph "Products Management"
+            N[POST /api/products]
+            O[PUT /api/products/{id}]
+            P[DELETE /api/products/{id}]
+        end
+        
+        subgraph "Categories Management"
+            Q[POST /api/categories]
+            R[PUT /api/categories/{id}]
+            S[DELETE /api/categories/{id}]
+        end
+        
+        subgraph "Shopping Cart"
+            T[GET /api/cart]
+            U[POST /api/cart/items]
+            V[PUT /api/cart/items/{pid}]
+            W[DELETE /api/cart/items/{pid}]
+            X[DELETE /api/cart]
+        end
+        
+        subgraph "Orders"
+            Y[POST /api/orders]
+            Z[GET /api/orders]
+            AA[GET /api/orders/{id}]
+            BB[PATCH /api/orders/{id}/cancel]
+        end
+    end
+    
+    %% Styling
+    classDef public fill:#c8e6c9
+    classDef protected fill:#ffcdd2
+    classDef management fill:#e1f5fe
+    classDef commerce fill:#fff3e0
+    
+    class A,B,C,D,E,F,G public
+    class H,I,J,K,L,M,N,O,P,Q,R,S protected
+    class T,U,V,W,X,Y,Z,AA,BB commerce
+```
+
+## 🔄 Fluxo do E-commerce
+
+```mermaid
+graph TD
+    A[👤 Usuário acessa sistema] --> B{Já registrado?}
+    B -->|Não| C[📝 Registro - POST /api/auth/register]
+    B -->|Sim| D[🔑 Login - POST /api/auth/login]
+    
+    C --> E[✅ Token JWT gerado]
+    D --> E
+    
+    E --> F[🏪 Navegar produtos - GET /api/products]
+    F --> G[🛒 Adicionar ao carrinho - POST /api/cart/items]
+    
+    G --> H{Continuar comprando?}
+    H -->|Sim| F
+    H -->|Não| I[📍 Verificar endereços - GET /api/users/me/addresses]
+    
+    I --> J{Tem endereço?}
+    J -->|Não| K[➕ Adicionar endereço - POST /api/users/me/addresses]
+    J -->|Sim| L[📋 Revisar carrinho - GET /api/cart]
+    
+    K --> L
+    L --> M[💳 Criar pedido - POST /api/orders]
+    M --> N[📦 Acompanhar pedidos - GET /api/orders]
+    
+    %% Styling
+    classDef start fill:#c8e6c9
+    classDef auth fill:#e1f5fe
+    classDef shop fill:#fff3e0
+    classDef order fill:#f3e5f5
+    
+    class A start
+    class B,C,D,E auth
+    class F,G,H shop
+    class I,J,K,L,M,N order
+```
\ No newline at end of file
diff --git a/docs/quick-reference.md b/docs/quick-reference.md
new file mode 100644
index 0000000..8589259
--- /dev/null
+++ b/docs/quick-reference.md
@@ -0,0 +1,66 @@
+# Quick Architecture Reference
+
+## 🏗️ High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Go Cart API                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐    │
+│  │   Client    │───▶│   Router     │───▶│   Middleware    │    │
+│  │ (HTTP/JSON) │    │(Gorilla Mux) │    │ (JWT Auth)      │    │
+│  └─────────────┘    └──────────────┘    └─────────────────┘    │
+│                                                   │             │
+│                                                   ▼             │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                   Handlers                              │    │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐   │    │
+│  │  │  Auth   │ │  User   │ │Product  │ │   Cart &    │   │    │
+│  │  │Handler  │ │Handler  │ │Handler  │ │   Orders    │   │    │
+│  │  └─────────┘ └─────────┘ └─────────┘ └─────────────┘   │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                   │             │
+│                                                   ▼             │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                 Repositories                            │    │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐   │    │
+│  │  │  User   │ │Product  │ │Category │ │ Cart/Order  │   │    │
+│  │  │  Repo   │ │  Repo   │ │  Repo   │ │    Repos    │   │    │
+│  │  └─────────┘ └─────────┘ └─────────┘ └─────────────┘   │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                   │             │
+│                                                   ▼             │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │               Database Layer                            │    │
+│  │                 PostgreSQL                              │    │
+│  │                (via Supabase)                          │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 🔧 Key Components
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| **Router** | Gorilla Mux | HTTP routing and URL handling |
+| **Auth** | JWT + bcrypt | User authentication and security |
+| **Handlers** | Go stdlib | HTTP request/response processing |
+| **Repositories** | pgx/v5 | Database abstraction layer |
+| **Database** | PostgreSQL | Data persistence (via Supabase) |
+
+## 📊 Data Flow
+
+```
+Request → Router → Auth Middleware → Handler → Repository → Database
+                                                      ↓
+Response ← JSON ← Processing ← Query Result ← PostgreSQL
+```
+
+## 🚀 Deployment
+
+- **Platform**: Render/Heroku
+- **Database**: Supabase (PostgreSQL)
+- **Port**: Auto-detected (4445+ range)
+- **Health Check**: `GET /api/health`
\ No newline at end of file
diff --git a/go-cart-api b/go-cart-api
new file mode 100755
index 0000000..f921785
Binary files /dev/null and b/go-cart-api differ
diff --git a/go.mod b/go.mod
index 5e88ca6..c022599 100644
--- a/go.mod
+++ b/go.mod
@@ -4,21 +4,25 @@ go 1.23.0
 
 toolchain go1.24.1
 
-require github.com/gorilla/mux v1.8.1
+require (
+	github.com/golang-jwt/jwt/v5 v5.2.2
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/mux v1.8.1
+	github.com/jackc/pgx/v5 v5.7.4
+	github.com/joho/godotenv v1.5.1
+	github.com/stretchr/testify v1.10.0
+	golang.org/x/crypto v0.37.0
+)
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/golang-jwt/jwt/v5 v5.2.2 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.7.4 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	github.com/joho/godotenv v1.5.1 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
-	github.com/stretchr/testify v1.10.0 // indirect
-	golang.org/x/crypto v0.37.0 // indirect
 	golang.org/x/sync v0.13.0 // indirect
 	golang.org/x/text v0.24.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
diff --git a/go.sum b/go.sum
index 68541b6..81d88b0 100644
--- a/go.sum
+++ b/go.sum
@@ -1,3 +1,4 @@
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -17,8 +18,14 @@ github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
@@ -26,19 +33,15 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
-golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE=
 golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc=
-golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
-golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.13.0 h1:AauUjRAJ9OSnvULf/ARrrVywoJDy0YS2AwQ98I37610=
 golang.org/x/sync v0.13.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
-golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
-golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
 golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0=
 golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/readme.md b/readme.md
index 96eff6f..6a1e3bc 100644
--- a/readme.md
+++ b/readme.md
@@ -324,6 +324,30 @@ Para rodar os testes unitários dos handlers:
 go test -v ./internal/handlers/...
 ```
 
+## 🏗️ Arquitetura
+
+Para visualizar a arquitetura completa do sistema, consulte nossa documentação técnica:
+
+### 📋 [Documentação Arquitetural Completa](./docs/README.md)
+
+Inclui diagramas detalhados de:
+- **Arquitetura Geral do Sistema**: Visão macro com todas as camadas
+- **Fluxo de Autenticação**: Processo de login/registro com JWT
+- **Modelo de Dados (ERD)**: Estrutura do banco PostgreSQL
+- **Fluxo de Requisições**: Como as requests são processadas
+- **Padrões Arquiteturais**: Clean Architecture e Repository Pattern
+
+### 🎯 Resumo Arquitetural
+
+**Padrão Principal**: Clean Architecture / Hexagonal
+- **Camadas bem separadas**: Handlers → Repositories → Database
+- **Inversão de dependências**: Interfaces para testabilidade
+- **Tecnologias**: Go + Gorilla Mux + PostgreSQL + JWT
+
+```
+Cliente → Router → Middleware → Handler → Repository → Database
+```
+
 ### 📄 Licença
 
 GNU-General-Public-License-v3.0
diff --git a/vendor/modules.txt b/vendor/modules.txt
index 25da756..67350f2 100644
--- a/vendor/modules.txt
+++ b/vendor/modules.txt
@@ -36,9 +36,13 @@ github.com/jackc/puddle/v2/internal/genstack
 # github.com/joho/godotenv v1.5.1
 ## explicit; go 1.12
 github.com/joho/godotenv
+# github.com/kr/text v0.2.0
+## explicit
 # github.com/pmezard/go-difflib v1.0.0
 ## explicit
 github.com/pmezard/go-difflib/difflib
+# github.com/rogpeppe/go-internal v1.14.1
+## explicit; go 1.23
 # github.com/stretchr/objx v0.5.2
 ## explicit; go 1.20
 github.com/stretchr/objx