omega-server/README.md

# Bootstrap App

A comprehensive web-based application built with clean architecture principles using Go and Fiber framework. This project serves as a robust foundation for building scalable web applications with advanced security features, role-based access control, and comprehensive API management.

## 🚀 Features

### Core Application Features
- **Clean Architecture**: Layered architecture with clear separation of concerns
- **RESTful API**: Comprehensive REST API with Swagger documentation
- **Database Management**: SQLite with GORM ORM and automatic migrations
- **Dependency Injection**: Uber Dig container for clean dependency management

### Security Features
- **JWT Authentication**: Secure token-based authentication system
- **Role-Based Access Control**: Granular permission system with user roles
- **Rate Limiting**: Protection against brute force and DoS attacks
- **Input Validation**: Comprehensive input sanitization and validation
- **Security Headers**: OWASP-compliant security headers
- **Password Security**: Bcrypt password hashing with strength validation
- **Audit Logging**: Comprehensive logging and audit trails

### Monitoring & Management
- **Health Checks**: Built-in health check endpoints
- **Request Logging**: Detailed HTTP request and response logging
- **Security Event Tracking**: Real-time security event monitoring
- **System Configuration**: Dynamic configuration management
- **Cache Management**: In-memory caching with TTL support

## 🏗️ Architecture

### Technology Stack
- **Backend**: Go 1.23.0 with Fiber web framework
- **Database**: SQLite with GORM ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **API Documentation**: Swagger/OpenAPI integration
- **Dependency Injection**: Uber Dig container
- **Caching**: In-memory cache with automatic cleanup

### Project Structure
```
omega-server/
├── cmd/
│   └── api/                    # Application entry point
├── local/
│   ├── api/                    # API route definitions
│   ├── controller/             # HTTP request handlers
│   ├── middleware/             # Authentication and security middleware
│   │   └── security/           # Advanced security middleware
│   ├── model/                  # Database models and business entities
│   ├── repository/             # Data access layer
│   ├── service/                # Business logic services
│   └── utl/                    # Utilities and shared components
│       ├── cache/              # Caching utilities
│       ├── common/             # Common utilities and types
│       ├── configs/            # Configuration management
│       ├── db/                 # Database connection and migration
│       ├── jwt/                # JWT token management
│       ├── logging/            # Logging utilities
│       ├── password/           # Password hashing utilities
│       └── server/             # HTTP server configuration
├── docs/                       # Documentation
├── scripts/                    # Utility scripts
│   ├── generate-secrets.ps1    # PowerShell secret generation
│   └── generate-secrets.sh     # Bash secret generation
├── logs/                       # Application logs
├── go.mod                      # Go module definition
├── .env.example               # Environment template
└── .gitignore                 # Git ignore rules
```

## 📋 Prerequisites

### System Requirements
- **Go**: Version 1.23.0 or later
- **Operating System**: Windows, Linux, or macOS
- **Memory**: Minimum 512MB RAM
- **Disk Space**: 100MB for application and logs

### Development Tools (Optional)
- **Air**: For hot reloading during development
- **Git**: For version control
- **Make**: For build automation
- **Docker**: For containerized deployment

## ⚙️ Installation

### 1. Clone or Copy the Project
```bash
# If using git
git clone <your-repository-url>
cd omega-server

# Or copy the bootstrap folder to your desired location
```

### 2. Generate Secure Secrets
We provide scripts to automatically generate secure secrets and create your `.env` file:

**Windows (PowerShell):**
```powershell
.\scripts\generate-secrets.ps1
```

**Linux/macOS (Bash):**
```bash
chmod +x scripts/generate-secrets.sh
./scripts/generate-secrets.sh
```

**Manual Setup:**
If you prefer to set up manually:
```bash
cp .env.example .env
```

Then generate secure secrets:
```bash
# JWT Secret (64 bytes, base64 encoded)
openssl rand -base64 64

# Application secrets (32 bytes, hex encoded)
openssl rand -hex 32

# Encryption key (16 bytes, hex encoded = 32 characters)
openssl rand -hex 16
```

### 3. Install Dependencies
```bash
go mod download
```

### 4. Build the Application
```bash
go build -o api.exe cmd/api/main.go
```

### 5. Run the Application
```bash
./api.exe
```

The application will be available at `http://localhost:3000`

## 🔧 Configuration

### Environment Variables

The application uses environment variables for configuration. Most critical settings are automatically generated by the secret generation scripts:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JWT_SECRET` | Yes | - | JWT signing secret (64+ chars, base64) |
| `APP_SECRET` | Yes | - | Application secret key (32 bytes, hex) |
| `APP_SECRET_CODE` | Yes | - | Application secret code (32 bytes, hex) |
| `ENCRYPTION_KEY` | Yes | - | AES-256 encryption key (32 hex chars) |
| `PORT` | No | 3000 | HTTP server port |
| `DB_NAME` | No | app.db | SQLite database filename |
| `CORS_ALLOWED_ORIGIN` | No | http://localhost:5173 | CORS allowed origin |
| `DEFAULT_ADMIN_PASSWORD` | No | - | Default admin password for initial setup |
| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARN, ERROR) |

### System Configuration

Advanced settings can be managed through the web interface after initial setup:
- **Security Policies**: Rate limits, session timeouts, password policies
- **Monitoring**: Logging levels, audit settings
- **Cache Settings**: TTL configuration, cache policies
- **API Configuration**: Rate limiting, request timeouts

## 🔒 Security

This application implements comprehensive security measures:

### Authentication & Authorization
- **JWT Tokens**: Secure token-based authentication with configurable TTL
- **Password Security**: Bcrypt hashing with strength validation
- **Role-Based Access**: Granular permission system
- **Session Management**: Configurable timeouts and automatic cleanup

### Protection Mechanisms
- **Rate Limiting**: Multiple layers of rate limiting (global and per-endpoint)
- **Input Validation**: Comprehensive input sanitization
- **Security Headers**: OWASP-compliant HTTP headers
- **CORS Protection**: Configurable cross-origin restrictions
- **Request Limits**: Size and timeout limitations

### Monitoring & Auditing
- **Security Events**: Authentication and authorization logging
- **Audit Trail**: Comprehensive activity logging with user tracking
- **Threat Detection**: Suspicious activity monitoring
- **Real-time Alerts**: Immediate notification of security events

## 📚 API Documentation

The application includes comprehensive API documentation via Swagger UI:
- **Local Development**: http://localhost:3000/swagger/
- **Interactive Testing**: Test API endpoints directly from the browser
- **Schema Documentation**: Complete request/response schemas

### Key API Endpoints

#### Health & Status
- `GET /health` - Health check endpoint
- `GET /ping` - Simple ping endpoint

#### Authentication
- `POST /api/v1/auth/login` - User authentication
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/refresh` - Refresh access token
- `POST /api/v1/auth/logout` - User logout

#### User Management
- `GET /api/v1/users` - List all users (paginated)
- `POST /api/v1/users` - Create new user
- `GET /api/v1/users/{id}` - Get user details
- `PUT /api/v1/users/{id}` - Update user
- `DELETE /api/v1/users/{id}` - Delete user

#### Role & Permission Management
- `GET /api/v1/roles` - List all roles
- `POST /api/v1/roles` - Create new role
- `GET /api/v1/permissions` - List all permissions
- `POST /api/v1/roles/{id}/permissions` - Assign permissions to role

#### System Management
- `GET /api/v1/system/config` - Get system configuration
- `PUT /api/v1/system/config` - Update system configuration
- `GET /api/v1/system/audit-logs` - Get audit logs
- `GET /api/v1/system/security-events` - Get security events

## 🛠️ Development

### Running in Development Mode
```bash
# Install air for hot reloading (optional)
go install github.com/cosmtrek/air@latest

# Run with hot reload
air

# Or run directly with go
go run cmd/api/main.go
```

### Environment Setup for Development
1. Copy `.env.example` to `.env`
2. Run the secret generation script
3. Set `LOG_LEVEL=DEBUG` for detailed logging
4. Set `DEBUG_MODE=true` for detailed error responses

### Database Management
```bash
# View database schema
sqlite3 app.db ".schema"

# View data
sqlite3 app.db "SELECT * FROM users;"

# Backup database
cp app.db app_backup.db
```

### Adding New Features

#### 1. Create a New Model
```go
// In local/model/your_model.go
type YourModel struct {
    BaseModel
    Name string `json:"name" gorm:"not null"`
    // Add your fields
}
```

#### 2. Create Repository
```go
// In local/repository/your_repository.go
type YourRepository struct {
    db *gorm.DB
}

func (r *YourRepository) Create(model *YourModel) error {
    return r.db.Create(model).Error
}
```

#### 3. Create Service
```go
// In local/service/your_service.go
type YourService struct {
    repo *repository.YourRepository
}

func (s *YourService) CreateItem(req CreateRequest) (*YourModel, error) {
    // Business logic here
}
```

#### 4. Create Controller
```go
// In local/controller/your_controller.go
type YourController struct {
    service *service.YourService
}

func (c *YourController) Create(ctx *fiber.Ctx) error {
    // Handle HTTP request
}
```

## 🚀 Production Deployment

### 1. Generate Production Secrets
```bash
# Use the secret generation script for production
./scripts/generate-secrets.sh  # Linux/macOS
.\scripts\generate-secrets.ps1  # Windows
```

### 2. Build for Production
```bash
# Build optimized binary
go build -ldflags="-w -s" -o omega-server.exe cmd/api/main.go
```

### 3. Security Checklist
- [ ] Generate unique production secrets (use provided scripts)
- [ ] Configure production CORS origins in `.env`
- [ ] Change default admin password immediately after first login
- [ ] Enable HTTPS with valid certificates
- [ ] Set up proper firewall rules
- [ ] Configure monitoring and alerting
- [ ] Set up log rotation
- [ ] Test all security configurations

### 4. Environment Variables for Production
```bash
# Set these in your production environment
GO_ENV=production
LOG_LEVEL=WARN
CORS_ALLOWED_ORIGIN=https://yourdomain.com
DEFAULT_ADMIN_PASSWORD=your-secure-password
```

### 5. Monitoring Setup
- Configure log rotation and retention
- Set up health check monitoring
- Configure alerting for critical errors
- Monitor resource usage and performance
- Set up database backup procedures

## 🔧 Troubleshooting

### Common Issues

#### "JWT_SECRET environment variable is required"
**Solution**: Run the secret generation script or manually set the JWT_SECRET environment variable.

#### "Failed to connect database"
**Solution**: Ensure the application has write permissions to the database directory and the database file doesn't exist or is accessible.

#### Database Migration Errors
**Solution**: Delete the database file and restart the application to recreate it with the latest schema:
```bash
rm app.db
./api.exe
```

#### Permission Denied Errors
**Solution**: Ensure the application has proper file system permissions:
```bash
# Linux/macOS
chmod +x api.exe
chmod 755 logs/

# Windows - Run as Administrator if needed
```

### Log Locations
- **Application Logs**: `./logs/app_YYYY-MM-DD.log`
- **Database File**: `./app.db` (or as configured in DB_NAME)
- **Environment Config**: `./.env`

### Debug Mode
Enable debug logging and detailed error messages:
```bash
# In .env file
LOG_LEVEL=DEBUG
DEBUG_MODE=true
```

## 📈 Performance Considerations

### Database Optimization
- Indexes are automatically created for frequently queried fields
- Use pagination for large result sets
- Consider database cleanup for old audit logs and security events

### Caching
- Built-in memory cache with configurable TTL
- Cache frequently accessed configuration data
- Automatic cleanup of expired cache entries

### Rate Limiting
- Adjust rate limits based on your application's needs
- Monitor rate limit metrics in production
- Consider implementing distributed rate limiting for multiple instances

## 🤝 Contributing

### Development Workflow
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes following the established patterns
4. Add tests for new functionality
5. Ensure all tests pass: `go test ./...`
6. Update documentation if needed
7. Commit your changes: `git commit -m 'Add amazing feature'`
8. Push to the branch: `git push origin feature/amazing-feature`
9. Open a Pull Request

### Code Style Guidelines
- Follow Go best practices and conventions
- Use `gofmt` for code formatting
- Add comprehensive comments for public functions
- Follow the established project structure
- Include error handling for all operations

### Adding New Dependencies
- Use `go mod tidy` after adding dependencies
- Ensure licenses are compatible
- Document any new dependencies in the README

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Fiber Framework**: High-performance HTTP framework for Go
- **GORM**: The fantastic ORM library for Go
- **Uber Dig**: Dependency injection container
- **JWT-Go**: JWT implementation for Go
- **Bcrypt**: Secure password hashing

## 📞 Support

### Documentation
- [API Documentation](http://localhost:3000/swagger/)
- [Architecture Guide](docs/ARCHITECTURE.md)
- [Security Guide](docs/SECURITY.md)
- [Deployment Guide](docs/DEPLOYMENT.md)

### Getting Help
- Check the [Troubleshooting](#troubleshooting) section
- Review the comprehensive inline code documentation
- Check existing issues in the repository
- Create a new issue with detailed information

---

**Happy Coding! 🚀**

Built with ❤️ using clean architecture principles and modern security practices.