almoq3-cli

v2.1.3

Published

a month ago

The high-performance Go framework for Laravel lovers.

0High
0Medium
0Low

   ▲
  ▲ ▲    almoq3 Framework

almoq3 — The Go Framework for Visionary Builders

High-performance Go backend. Modern React frontend. One command to rule them all.

Built for developers who refuse to compromise on speed, elegance, or developer experience.

📖 Documentation · 🚀 Quick Start · ✨ Features · 📦 Installation · 🗺️ Roadmap

What is almoq3?

almoq3 (المعقد) is a full-stack enterprise framework that brings the developer experience of Laravel to the raw performance of Go. It scaffolds production-ready applications with a single command, eliminating the configuration overhead that typically plagues Go projects.

Think of it as Laravel for Go — but with React and shadcn/ui built-in from day one.

The Problem We Solve

Starting a production-ready Go web application today requires:

✘ Manually wiring together Fiber/Gin, GORM, Redis, Zap, JWT...
✘ Setting up Docker, migrations, seeders, middleware from scratch
✘ Building a separate React frontend and bridging it to Go
✘ Hours of boilerplate before writing a single line of business logic

almoq3 solves all of this in under 60 seconds.

Quick Start

# Install the CLI globally
npm install -g almoq3-cli

# Create a new full-stack project
almoq3 new my-awesome-app

# Navigate and run
cd my-awesome-app
go run main.go

Open http://localhost:3000 — your full-stack app is live. ✨

Features

🏗️ Instant Full-Stack Scaffolding

One command creates a complete project structure:

my-app/
├── app/
│   ├── controllers/      # HTTP handlers (RESTful CRUD)
│   ├── models/           # GORM models
│   ├── services/         # Business logic layer
│   ├── middleware/        # Custom middleware
│   └── requests/         # Form validation
├── bootstrap/            # App initialization (Config, DB, Cache, Logger)
├── config/               # Typed configuration (Viper-powered)
├── database/
│   ├── migrations/       # SQL migrations with tracking
│   └── seeders/          # Database seeders
├── routes/
│   ├── api.go            # API routes (versioned)
│   └── web.go            # Web routes (serves React build)
├── frontend/             # React + Vite + shadcn/ui
│   ├── src/
│   │   ├── App.jsx       # Welcome Page
│   │   ├── UIShowcase.jsx
│   │   └── main.jsx
│   ├── vite.config.js
│   └── tailwind.config.js
├── public/               # Built frontend assets (auto-generated)
├── storage/logs/         # Rotating log files
├── cmd/seed/             # Database seeder entry point
├── Dockerfile            # Multi-stage production build
├── docker-compose.yml    # Full stack with PostgreSQL + Redis
├── almoq3.json           # Framework metadata & version tracking
└── .env                  # Environment configuration

⚡ Performance Core (Go + Fiber)

Built on Fiber — the fastest Go web framework (Express.js-inspired)
GORM ORM with multi-database support (PostgreSQL, MySQL, SQLite)
Zero-cost abstractions — no reflection overhead in hot paths
Handles millions of requests per second on commodity hardware

🎨 Modern Frontend Engine (React + shadcn/ui)

React 18 with Vite for lightning-fast HMR
Tailwind CSS with full shadcn/ui component library
Radix UI primitives for accessible, production-quality components
Fully automated: npm install + npm run build run automatically on almoq3 new
Go server serves the built assets with proper client-side routing fallback

🛠️ The CLI Command Suite

| Command | Description | |---|---| | almoq3 new <name> | Scaffold a complete full-stack project | | almoq3 run | Start the development server (cross-platform) | | almoq3 upgrade | Safely upgrade framework files without touching user code | | almoq3 make:controller <Name> | Generate a RESTful controller | | almoq3 make:model <Name> | Generate a GORM model | | almoq3 make:service <Name> | Generate a service layer class | | almoq3 make:middleware <Name> | Generate middleware | | almoq3 make:request <Name> | Generate form request validator | | almoq3 make:migration <name> | Generate a timestamped SQL migration | | almoq3 migrate | Run pending migrations | | almoq3 migrate:rollback | Roll back the last migration batch | | almoq3 make:seeder <Name> | Generate a database seeder | | almoq3 db:seed | Execute database seeders | | almoq3 make:auth | Scaffold complete JWT authentication system | | almoq3 make:job <Name> | Generate a background job | | almoq3 make:test <Name> | Generate a test suite file | | almoq3 ui:install | Install/upgrade the React frontend in existing projects | | almoq3 key:generate | Generate a secure APP_KEY | | almoq3 self-update | Update the CLI binary to the latest version |

🔐 Authentication (JWT) — One Command

almoq3 make:auth

Generates 4 production-ready files:

app/controllers/AuthController.go — Register, Login, Logout, Me
app/models/User.go — User model with bcrypt password hashing
app/middleware/JwtMiddleware.go — Route protection middleware
database/migrations/xxxx_create_users_table.sql — Users table

📦 Production-Ready Infrastructure

Logging — Structured logging via Uber Zap with Lumberjack rotation:

logger.Info("Request processed", zap.String("path", c.Path()), zap.Int("status", 200))

Caching — Redis integration with a clean wrapper API:

cache.Set("key", value, 5*time.Minute)
cache.Get("key")

Configuration — Strongly-typed config via Viper:

config.App.Name       // string
config.Database.Port  // int
config.App.Debug      // bool

Background Jobs — Redis-based async job processing:

almoq3 make:job SendEmailJob

🐳 Docker Ready

Every project ships with:

Multi-stage Dockerfile — final image under 20MB
docker-compose.yml — full stack with PostgreSQL, Redis, and the app

docker-compose up -d

🧪 Testing

almoq3 make:test UserTest

Generates test files using Go's native testing package with an in-memory SQLite database — no external dependencies required for tests.

The Smart Upgrade System

One of almoq3's most powerful features is zero-risk project upgrades.

almoq3 upgrade

╔══════════════════════════════════════════════╗
║       almoq3 Smart Project Upgrade           ║
╚══════════════════════════════════════════════╝
  Project:  my-awesome-app
  Current:  v1.0.0
  Latest:   v2.1.1

🛡️ Your controllers, models, routes, and migrations are SAFE.

  ✓ Updated: frontend/src/App.jsx
  ✓ Updated: frontend/src/UIShowcase.jsx
  ✓ Updated: routes/web.go
  ... (8 files total)
  ✓ Frontend assets rebuilt.

╔══════════════════════════════════════════════╗
║           Upgrade Complete! 🎉               ║
╚══════════════════════════════════════════════╝
  Version: v1.0.0 → v2.1.1

What gets updated (framework-owned):

frontend/src/App.jsx — Welcome page & UI
frontend/src/UIShowcase.jsx — Component showcase
frontend/vite.config.js, tailwind.config.js
routes/web.go — Static serving logic

What is NEVER touched (user-owned):

app/controllers/ · app/models/ · app/services/
routes/api.go · database/migrations/ · .env
Any file you created yourself

Update Notifications

Whenever a new version is released, every almoq3 command will display:

╔══════════════════════════════════════════════════════════╗
║  🚀 almoq3 Update Available!                             ║
║  Current: v2.0.4     Latest: v2.1.1                     ║
║                                                          ║
║  1. Update CLI:     npm i -g almoq3-cli@latest           ║
║  2. Upgrade project: almoq3 upgrade                      ║
╚══════════════════════════════════════════════════════════╝

Non-blocking — your command still runs. The notification appears after completion.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    almoq3 Framework                     │
├──────────────────────────┬──────────────────────────────┤
│      Go Backend          │      React Frontend          │
│                          │                              │
│  Fiber (HTTP Router)     │  Vite + React 18             │
│  GORM (ORM)              │  Tailwind CSS                │
│  Viper (Config)          │  shadcn/ui Components        │
│  Zap (Logging)           │  Radix UI Primitives         │
│  Redis (Cache/Jobs)      │  Client-side Routing         │
│  JWT (Auth)              │                              │
│  bcrypt (Passwords)      │  Built → /public/            │
│  SQLite (Testing)        │  Served by Go ←──────────────┤
│                          │                              │
├──────────────────────────┴──────────────────────────────┤
│                   CLI Engine                            │
│                                                         │
│  Cobra (Commands) · Embedded Templates (go:embed)       │
│  Auto npm install/build · Smart upgrade system          │
│  GitHub update checker · Cross-platform (Win/Mac/Linux) │
└─────────────────────────────────────────────────────────┘

Installation

Requirements

| Tool | Minimum Version | |---|---| | Go | 1.21+ | | Node.js | 18+ | | npm | 9+ |

Install the CLI

npm install -g almoq3-cli

Verify

almoq3 --version
# almoq3 version 2.1.1

Documentation

Environment Configuration (`.env`)

APP_NAME=my-app
APP_ENV=local
APP_DEBUG=true
APP_PORT=3000
APP_KEY=base64:your-32-char-secret-here

DB_DRIVER=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=postgres
DB_PASSWORD=secret

REDIS_HOST=localhost
REDIS_PORT=6379

Creating a Controller

almoq3 make:controller Product

Generates app/controllers/ProductController.go:

func (pc *ProductController) Index(c *fiber.Ctx) error {
    // GET /api/products
}
func (pc *ProductController) Store(c *fiber.Ctx) error {
    // POST /api/products
}
func (pc *ProductController) Show(c *fiber.Ctx) error {
    // GET /api/products/:id
}
func (pc *ProductController) Update(c *fiber.Ctx) error {
    // PUT /api/products/:id
}
func (pc *ProductController) Destroy(c *fiber.Ctx) error {
    // DELETE /api/products/:id
}

Database Migrations

almoq3 make:migration create_products_table
# Creates: database/migrations/20260515_143022_create_products_table.up.sql

almoq3 migrate          # Run all pending migrations
almoq3 migrate:rollback # Roll back last batch

JWT Authentication

almoq3 make:auth
almoq3 migrate

# Now you have:
# POST /api/auth/register
# POST /api/auth/login
# GET  /api/auth/me       (protected)
# POST /api/auth/logout   (protected)

Comparison

| Feature | almoq3 | Raw Go | Laravel | |---|:---:|:---:|:---:| | Instant scaffolding | ✅ | ❌ | ✅ | | Go performance | ✅ | ✅ | ❌ | | Built-in ORM | ✅ | ❌ | ✅ | | Auth scaffolding | ✅ | ❌ | ✅ | | React frontend | ✅ | ❌ | ❌ | | Docker ready | ✅ | ❌ | ⚠️ | | Safe upgrades | ✅ | ❌ | ⚠️ | | Background jobs | ✅ | ❌ | ✅ | | CLI code generators | ✅ | ❌ | ✅ | | Cross-platform | ✅ | ✅ | ✅ |

Roadmap

[x] Core scaffolding engine
[x] GORM + multi-database support
[x] JWT authentication generator
[x] React + shadcn/ui frontend integration
[x] Smart project upgrade system
[x] Background jobs (Redis)
[x] Docker + production deployment
[x] Update notifications
[ ] almoq3 make:ui — scaffold individual shadcn components
[ ] WebSocket support
[ ] GraphQL generator
[ ] Official documentation website
[ ] VS Code extension

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

git clone https://github.com/mustfamoolan/almoq3cli.git
cd "almoq3cli/almoq3 Framework"
go build -o almoq3.exe main.go
./almoq3.exe new test-project

License

Built with ❤️ in Iraq 🇮🇶

GitHub · NPM · Report Bug