Revise README for clarity and organization

Updated README with improved project description and structure.

Author: Bulletdev

readme.md

@@ -1,98 +1,112 @@
 
 # Bullet Cloud API: E-commerce Backend
 [![CodeQL Advanced](https://github.com/Bulletdev/bullet-cloud-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/Bulletdev/bullet-cloud-api/actions/workflows/codeql.yml)
+[![Go](https://github.com/Bulletdev/bullet-cloud-api/actions/workflows/go.yml/badge.svg)](https://github.com/Bulletdev/bullet-cloud-api/actions/workflows/go.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Bulletdev_Arremate-certo&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Bulletdev_Arremate-certo)
 ![Go Version](https://img.shields.io/github/go-mod/go-version/Bulletdev/go-cart-api?color=00ADD8&labelColor=000000)
 ![License](https://img.shields.io/badge/license-GPL--3.0-blue)
 
-Uma API RESTful de alta performance desenvolvida em Go, projetada sob princípios de Clean Architecture. Focada em segurança (IAM), escalabilidade e gestão de ecossistemas de e-commerce modernos.
+API RESTful de alta performance desenvolvida em Go, focada em segurança (IAM), escalabilidade e padrões de Clean Architecture. Ideal para ecossistemas de e-commerce que exigem auditoria e integridade de dados.
 
 ---
 
-##  Stack 
+##  Arquitetura e Design System
+O projeto implementa o padrão **Hexagonal / Clean Architecture**, garantindo total desacoplamento entre a lógica de negócio e os provedores de infraestrutura.
 
-| Camada | Tecnologia |
-| :--- | :--- |
-| **Linguagem** | Go (1.22+) |
-| **Roteamento** | Gorilla Mux |
-| **Persistência** | PostgreSQL (via pgx/v5) |
-| **Segurança** | JWT (v5) & Bcrypt |
-| **Migrações** | Golang-migrate |
-| **Observabilidade** | Prometheus & Grafana (Planned) |
+
+
+### Core Principles
+- **DevSecOps Integrado:** CodeQL e análise estática SonarCloud no pipeline de CI.
+- **Data Integrity:** Controle de transações ACID no PostgreSQL e migrações versionadas.
+- **IAM:** Autenticação via JWT (v5) e hashing robusto com Bcrypt.
+- **Scalability:** Design stateless e interfaces para repositórios facilitando substituição de DB ou Mocking em testes.
 
 ---
 
-##  Arquitetura e Design
-A aplicação implementa o padrão **Hexagonal / Clean Architecture**, isolando a lógica de negócio (Domain/Repositories) da infraestrutura e dos transportes (Handlers/Middlewares).
+##  Guia de Uso (Exemplos Rápidos)
 
+<details>
+<summary><b>Autenticação e Registro</b></summary>
 
+**Registrar novo usuário:**
+```bash
+curl -X POST http://localhost:4444/api/auth/register \
+-H "Content-Type: application/json" \
+-d '{"name":"Michael Bullet","email":"[email protected]","password":"senha_segura"}'
 
-### Destaques do Projeto
-- **DevSecOps Ready:** CodeQL e análise estática via SonarCloud integrados ao CI/CD.
-- **Data Integrity:** Controle rigoroso de transações e migrações versionadas.
-- **RESTful Design:** Endpoints padronizados com prefixo `/api` e status codes semânticos.
-- **High Testability:** Handlers desacoplados via interfaces para facilitação de mocks e testes unitários.
+```
 
----
+**Login e Obtenção de Token:**
 
-## Visão Geral da API
+```bash
+TOKEN=$(curl -s -X POST http://localhost:4444/api/auth/login \
+-H "Content-Type: application/json" \
+-d '{"email":"[email protected]","password":"senha_segura"}' | jq -r .token)
 
-<details>
-<summary><b> Autenticação e Gestão de Identidade (IAM)</b></summary>
+```
 
-| Método | Endpoint | Descrição |
-| :--- | :--- | :--- |
-| POST | `/api/auth/register` | Registro de novo usuário |
-| POST | `/api/auth/login` | Autenticação e emissão de JWT |
-| GET | `/api/users/me` | Recupera perfil do portador do token |
 </details>
 
 <details>
-<summary><b> Carrinho de Compras e Pedidos</b></summary>
-
-| Método | Endpoint | Descrição |
-| :--- | :--- | :--- |
-| GET | `/api/cart` | Visualiza o estado atual do carrinho |
-| POST | `/api/cart/items` | Adiciona ou incrementa itens |
-| DELETE | `/api/cart/items/{id}` | Remove item específico |
-| POST | `/api/orders` | Checkout e conversão de carrinho em pedido |
-| GET | `/api/orders` | Lista histórico de pedidos |
-</details>
+<summary><b>Gerenciamento de Carrinho</b></summary>
+
+**Adicionar Item:**
+
+```bash
+curl -X POST http://localhost:4444/api/cart/items \
+-H "Authorization: Bearer $TOKEN" \
+-H "Content-Type: application/json" \
+-d '{"product_id":"UUID_DO_PRODUTO","quantity":2}'
+
+```
+
+**Checkout (Gerar Pedido):**
+
+```bash
+curl -X POST http://localhost:4444/api/orders -H "Authorization: Bearer $TOKEN"
+
+```
 
-<details>
-<summary><b> Catálogo de Produtos</b></summary>
-
-| Método | Endpoint | Descrição |
-| :--- | :--- | :--- |
-| GET | `/api/products` | Listagem geral com filtros (Planned) |
-| GET | `/api/products/{id}` | Detalhes técnicos do produto |
-| POST | `/api/products` | Criação de novos SKUs (Admin Only) |
-| GET | `/api/categories` | Listagem de categorias ativas |
 </details>
 
 ---
 
-## Configuração e Execução
+##  Documentação da API
+
+| Módulo | Método | Endpoint | Protegido |
+| --- | --- | --- | --- |
+| **Auth** | POST | `/api/auth/login` | No |
+| **Users** | GET | `/api/users/me` | Yes |
+| **Products** | GET | `/api/products` | No |
+| **Cart** | POST | `/api/cart/items` | Yes |
+| **Orders** | GET | `/api/orders` | Yes |
+
+> [Consulte a Documentação Arquitetural Detalhada](https://www.google.com/search?q=./docs/README.md) para diagramas de ERD e fluxos de autenticação.
+
+---
+
+##  Configuração do Ambiente
 
 ### Pré-requisitos
-- Go 1.22+
-- PostgreSQL
-- [Golang-migrate CLI](https://github.com/golang-migrate/migrate)
 
-### Setup Rápido
-1. **Clone & Install:**
-   ```bash
-   git clone [https://github.com/bulletdev/go-cart-api.git](https://github.com/bulletdev/go-cart-api.git)
-   cd go-cart-api && go mod tidy
+* Go 1.22+
+* PostgreSQL (ou Supabase)
+* [Golang-migrate CLI](https://github.com/golang-migrate/migrate)
+
+### Setup
+
+1. **Instalação:**
+```bash
+git clone [https://github.com/bulletdev/go-cart-api.git](https://github.com/bulletdev/go-cart-api.git)
+cd go-cart-api && go mod tidy
 
 ```
 
-2. **Environment:**
-Crie um arquivo `.env` baseado nas variáveis abaixo:
+
+2. **Ambiente (.env):**
 ```env
-DATABASE_URL="postgres://user:pass@host:5432/db?sslmode=require"
-JWT_SECRET="sua_chave_secreta_aqui"
-API_PORT=4444
+DATABASE_URL="postgres://usuario:senha@host:5432/database"
+JWT_SECRET="seu_segredo_jwt"
 
 ```
 
@@ -104,7 +118,7 @@ migrate -database ${DATABASE_URL} -path internal/database/migrations up
 ```
 
 
-4. **Run:**
+4. **Execução:**
 ```bash
 go run cmd/main.go
 
@@ -114,9 +128,9 @@ go run cmd/main.go
 
 ---
 
-##  Qualidade de Código
+##  Qualidade e Testes
 
-Execução de suíte de testes unitários:
+Suíte de testes unitários focada em Handlers e Lógica de Negócio:
 
 ```bash
 go test -v ./internal/handlers/...
@@ -125,15 +139,10 @@ go test -v ./internal/handlers/...
 
 ---
 
-## 📄 Licença
-
-Distribuído sob a licença **GNU General Public License v3.0**. Veja `LICENSE` para mais informações.
-
-##  Contato
-
-Michael Bullet 
+## 📄 Licença e Contato
 
-[[email protected]](mailto:[email protected])
-[michaelbullet.com](https://www.michaelbullet.com)
+* **Licença:** GNU General Public License v3.0
+* **Autor:** Michael Bullet - [[email protected]](mailto:[email protected])
+* **Web:** [michaelbullet.com](https://www.michaelbullet.com)
 
 ```