Generete Module Handler
This commit is contained in:
289
LAYOUT.md
Normal file
289
LAYOUT.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 📊 API Service Project Layout
|
||||
|
||||
## 🎯 Project Overview Dashboard
|
||||
|
||||
### 📈 Key Metrics
|
||||
- **Language**: Go 1.24.4
|
||||
- **Framework**: Gin 1.10.1
|
||||
- **Database**: PostgreSQL with GORM
|
||||
- **Authentication**: JWT + Keycloak
|
||||
- **Documentation**: Swagger/OpenAPI 3.0
|
||||
- **Container**: Docker & Docker Compose
|
||||
|
||||
### 🏗️ Architecture Overview
|
||||
```
|
||||
api-service/
|
||||
├── cmd/
|
||||
│ └── api/
|
||||
│ └── main.go
|
||||
├── internal/
|
||||
│ ├── config/ # Config loader
|
||||
│ ├── server/ # HTTP server setup + routes binding
|
||||
│ ├── handler/ # HTTP handlers (controller layer)
|
||||
│ ├── service/ # Business logic
|
||||
│ ├── repository/ # DB access layer
|
||||
│ ├── model/ # App/domain models
|
||||
│ └── middleware/ # HTTP middlewares
|
||||
├── pkg/ # Reusable packages independent of business logic
|
||||
│ ├── logger/
|
||||
│ ├── utils/
|
||||
│ └── validator/
|
||||
├── scripts/ # Deployment & build automation
|
||||
└── docs/ # Documentation (incl. swagger)
|
||||
```
|
||||
|
||||
## 🚀 Development Environment Layout
|
||||
|
||||
### 📋 Prerequisites Setup
|
||||
```bash
|
||||
# Required tools
|
||||
- Go 1.24.4+
|
||||
- PostgreSQL 12+
|
||||
- Docker & Docker Compose
|
||||
- Keycloak Server (optional)
|
||||
|
||||
# Development tools
|
||||
- Air (hot reload)
|
||||
- Swag (Swagger docs)
|
||||
- Make (build automation)
|
||||
```
|
||||
|
||||
### 🔧 Configuration Files Layout
|
||||
```
|
||||
project-root/
|
||||
├── .env # Environment variables
|
||||
├── .air.toml # Air configuration
|
||||
├── Makefile # Build commands
|
||||
├── docker-compose.yml # Docker services
|
||||
├── Dockerfile # Container image
|
||||
└── .goreleaser.yml # Release configuration
|
||||
```
|
||||
|
||||
## 📚 API Documentation Layout
|
||||
|
||||
### 🌐 Base URL Structure
|
||||
```
|
||||
http://localhost:8080/api/v1
|
||||
```
|
||||
|
||||
### 📖 Endpoint Categories
|
||||
|
||||
#### 🔍 Health & Monitoring
|
||||
- `GET /api/v1/health` - Health check
|
||||
- `GET /api/v1/` - Hello world
|
||||
- `GET /api/v1/metrics` - Application metrics
|
||||
|
||||
#### 🔐 Authentication Endpoints
|
||||
- `POST /api/v1/auth/login` - User login
|
||||
- `POST /api/v1/auth/register` - User registration
|
||||
- `POST /api/v1/auth/refresh` - Token refresh
|
||||
- `POST /api/v1/auth/logout` - User logout
|
||||
|
||||
#### 👤 User Management
|
||||
- `GET /api/v1/users/profile` - Get user profile
|
||||
- `PUT /api/v1/users/profile` - Update user profile
|
||||
- `GET /api/v1/users` - List users (admin)
|
||||
- `GET /api/v1/users/:id` - Get user by ID
|
||||
|
||||
#### 📦 Product Management
|
||||
- `GET /api/v1/products` - List products
|
||||
- `POST /api/v1/products` - Create product
|
||||
- `GET /api/v1/products/:id` - Get product
|
||||
- `PUT /api/v1/products/:id` - Update product
|
||||
- `DELETE /api/v1/products/:id` - Delete product
|
||||
|
||||
#### 🔄 Real-time Features
|
||||
- `GET /api/v1/websocket` - WebSocket connection
|
||||
- `GET /api/v1/webservice` - Web service endpoint
|
||||
|
||||
### 📊 Swagger Documentation
|
||||
- **Interactive UI**: http://localhost:8080/swagger/index.html
|
||||
- **OpenAPI JSON**: http://localhost:8080/swagger/doc.json
|
||||
|
||||
## 🐳 Docker Deployment Layout
|
||||
|
||||
### 🏃 Development Environment
|
||||
```bash
|
||||
# Start all services
|
||||
make docker-run
|
||||
|
||||
# Services included:
|
||||
- PostgreSQL database
|
||||
- API service with hot reload
|
||||
- pgAdmin (database management)
|
||||
```
|
||||
|
||||
### 🚀 Production Environment
|
||||
```bash
|
||||
# Build production image
|
||||
docker build -t api-service:prod .
|
||||
|
||||
# Run production container
|
||||
docker run -d \
|
||||
-p 8080:8080 \
|
||||
--env-file .env \
|
||||
--name api-service \
|
||||
api-service:prod
|
||||
```
|
||||
|
||||
### 📦 Docker Compose Services
|
||||
```yaml
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
environment:
|
||||
POSTGRES_DB: api_service
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
|
||||
api:
|
||||
build: .
|
||||
ports:
|
||||
- "8080:8080"
|
||||
depends_on:
|
||||
- postgres
|
||||
environment:
|
||||
- BLUEPRINT_DB_HOST=postgres
|
||||
volumes:
|
||||
- .:/app
|
||||
command: air -c .air.toml
|
||||
```
|
||||
|
||||
## 🛠️ Development Workflow Layout
|
||||
|
||||
### 🔄 Daily Development Cycle
|
||||
```bash
|
||||
# 1. Start development environment
|
||||
make watch
|
||||
|
||||
# 2. Run tests
|
||||
make test
|
||||
|
||||
# 3. Check code quality
|
||||
make lint
|
||||
|
||||
# 4. Build for production
|
||||
make build
|
||||
```
|
||||
|
||||
### 🧪 Testing Strategy
|
||||
```
|
||||
tests/
|
||||
├── unit/ # Unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── e2e/ # End-to-end tests
|
||||
└── fixtures/ # Test data
|
||||
```
|
||||
|
||||
### 📊 Monitoring & Logging
|
||||
- **Health Check**: `/api/v1/health`
|
||||
- **Metrics**: Prometheus metrics
|
||||
- **Logging**: Structured JSON logs
|
||||
- **Tracing**: Distributed tracing support
|
||||
|
||||
## 📁 File Structure Detailed Layout
|
||||
|
||||
### 📄 Configuration Files
|
||||
```
|
||||
.env.example # Environment template
|
||||
config/
|
||||
├── config.go # Configuration struct
|
||||
├── config_test.go # Configuration tests
|
||||
└── validation.go # Config validation
|
||||
```
|
||||
|
||||
### 🗄️ Database Layout
|
||||
```
|
||||
database/
|
||||
├── migrations/ # Database migrations
|
||||
├── seeds/ # Seed data
|
||||
├── models/ # GORM models
|
||||
└── repositories/ # Data access layer
|
||||
```
|
||||
|
||||
### 🎯 Handler Layout
|
||||
```
|
||||
handlers/
|
||||
├── auth.go # Authentication handlers
|
||||
├── user.go # User management handlers
|
||||
├── product.go # Product handlers
|
||||
├── health.go # Health check handlers
|
||||
└── middleware/ # HTTP middleware
|
||||
├── auth.go # JWT middleware
|
||||
├── cors.go # CORS middleware
|
||||
└── logger.go # Logging middleware
|
||||
```
|
||||
|
||||
### 🌐 Route Layout
|
||||
```
|
||||
routes/
|
||||
├── v1/
|
||||
│ ├── routes.go # Route definitions
|
||||
│ ├── auth_routes.go # Auth routes
|
||||
│ ├── user_routes.go # User routes
|
||||
│ └── product_routes.go # Product routes
|
||||
└── middleware.go # Route middleware
|
||||
```
|
||||
|
||||
## 🚀 Quick Start Commands
|
||||
|
||||
### 🏃 Development
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone <repo-url>
|
||||
cd api-service
|
||||
cp .env.example .env
|
||||
make docker-run
|
||||
|
||||
# Start development
|
||||
make watch
|
||||
```
|
||||
|
||||
### 🧪 Testing
|
||||
```bash
|
||||
# Run all tests
|
||||
make all
|
||||
|
||||
# Run specific test
|
||||
make test
|
||||
make itest
|
||||
```
|
||||
|
||||
### 🚀 Production
|
||||
```bash
|
||||
# Build and run
|
||||
make build
|
||||
./main.exe
|
||||
```
|
||||
|
||||
## 📊 Performance Monitoring Layout
|
||||
|
||||
### 📈 Metrics Collection
|
||||
- **Request Duration**: Track API response times
|
||||
- **Error Rates**: Monitor error frequencies
|
||||
- **Database Performance**: Query execution times
|
||||
- **Memory Usage**: Application memory consumption
|
||||
|
||||
### 🔍 Health Checks
|
||||
- **Database Connectivity**: PostgreSQL connection status
|
||||
- **External Services**: Keycloak availability
|
||||
- **Resource Usage**: CPU and memory utilization
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **Setup Environment**: Copy `.env.example` to `.env`
|
||||
2. **Start Database**: Run `make docker-run`
|
||||
3. **Start Development**: Run `make watch`
|
||||
4. **Test API**: Visit `http://localhost:8080/swagger/index.html`
|
||||
5. **Run Tests**: Execute `make all`
|
||||
|
||||
## 📞 Support & Resources
|
||||
|
||||
- **Documentation**: Check `/docs` folder
|
||||
- **API Testing**: Use Swagger UI at `/swagger/index.html`
|
||||
- **Database**: Access pgAdmin at `http://localhost:5050`
|
||||
- **Issues**: Create GitHub issues for bugs/features
|
||||
Reference in New Issue
Block a user