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

# 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):

.\scripts\generate-secrets.ps1

Linux/macOS (Bash):

chmod +x scripts/generate-secrets.sh
./scripts/generate-secrets.sh

Manual Setup: If you prefer to set up manually:

cp .env.example .env

Then generate secure secrets:

# 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

go mod download

4. Build the Application

go build -o api.exe cmd/api/main.go

5. Run the Application

./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

# 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

Copy .env.example to .env
Run the secret generation script
Set LOG_LEVEL=DEBUG for detailed logging
Set DEBUG_MODE=true for detailed error responses

Database Management

# 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

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

2. Create Repository

// 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

// 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

// 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

# Use the secret generation script for production
./scripts/generate-secrets.sh  # Linux/macOS
.\scripts\generate-secrets.ps1  # Windows

2. Build for Production

# 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

# 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:

rm app.db
./api.exe

Permission Denied Errors

Solution: Ensure the application has proper file system permissions:

# 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:

# 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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes following the established patterns
Add tests for new functionality
Ensure all tests pass: go test ./...
Update documentation if needed
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
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 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

Getting Help

Check the 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.