A modular application framework for Zig 0.16.0, inspired by Spring Modulith. Build scalable applications from monolithic to distributed systems with progressive architecture evolution.
| Guide | Description |
|---|---|
| Quick Start | Get started in 5 minutes |
| Best Practices | Architecture evolution from 1K to 1M+ DAU |
| API Reference | Detailed API documentation |
| Architecture | System design and patterns |
| Evaluation Report | Production readiness assessment (75/100) |
| Examples | Runnable example projects |
| ZModu CLI | Code generator for modules, ORM, APIs (npm i -g @chy3xyz/zmodu) |
- Module System — Declarative module definition with compile-time dependency validation
- Lifecycle Management — Automatic init/deinit orchestration in dependency order
- Dependency Injection — Type-safe container with compile-time hash checking (CRC32)
- Event System — TypedEventBus + DistributedEventBus + TransactionalEvent + Outbox pattern
- Application Builder — Fluent API with shutdown hooks and graceful termination
- HTTP Server — Async fiber-based server (kqueue/io_uring), trie router, middleware chains
- WebSocket — RFC 6455 server/client with origin validation and monitoring
- gRPC
⚠️ — Service registry + Proto parser + 16 status codes (experimental) - OpenAPI — 3.0/3.1 JSON document generator from route metadata
- Idempotency — Request deduplication middleware with TTL-based store
- Circuit Breaker — Three-state (closed/open/half-open) with configurable thresholds
- Rate Limiter — Token bucket with per-client overrides
- Retry Policy — Exponential backoff with configurable jitter
- Load Shedder — Adaptive concurrency limiting
- Saga Orchestrator — Automatic compensation with reverse-order rollback + step logging
- SQLx — PostgreSQL / MySQL / SQLite with connection pooling + circuit breaker
- ORM — Type-safe repository pattern with compile-time table mapping
- Database Migrations — Flyway/Liquibase-style versioned migrations with SHA256 checksums
- Cache Manager — LRU cache with TTL expiration
- Redis Client — Connection pooling and command pipeline
- Connection Pool — Generic resource pool with health checking
- DistributedEventBus — Cross-node event pub/sub with heartbeat
- ClusterMembership
⚠️ — Gossip-based node discovery + health check (experimental) - DistributedTransaction
⚠️ — 2PC + Saga patterns (experimental, needs persistence) - Kafka Connector — Producer/Consumer with topic stats + EventBridge
- Sharding — Tenant-aware ShardRouter with configurable pools
- Distributed Tracing — OpenTelemetry-compatible, Jaeger/Zipkin export
- Prometheus Metrics — Counter / Gauge (lock-free CAS) / Histogram / Summary
- Structured Logging — JSON-formatted with log rotation and levels
- Auto Instrumentation — Automatic lifecycle/event/API instrumentation
- Health Endpoints — K8s-compatible liveness/readiness/module-health probes
- JWT Authentication — Token generation/verification with expiry
- RBAC — Role-based access control
- Password Encoder — Scrypt-based password hashing
- Security Scanner — Static SAST with configurable rules
- Secrets Manager — Multi-source secrets (env > file > Vault > default) with priority resolution
- Multi-Tenancy — TenantContext + DataPermission + ShardRouter
- Architecture Tester — Compile-time dependency rule validation
- Module Interaction Verifier — Spring Modulith verify()-style interaction model checking
- Contract Testing — Pact-style consumer-driven contract verification
- Plugin System
⚠️ — Dynamic extension loading (experimental) - Web Monitor
⚠️ — HTTP dashboard for module inspection (experimental) - Hot Reloader
⚠️ — File-watch based module change detection (experimental) - CI/CD Pipeline — GitHub Actions: matrix build (linux/macOS), lint, benchmark, Docker, release
For large projects, import only the domains you need:
const zmodu = @import("zigmodu");
// Full import (everything):
var app = try zmodu.builder(allocator, io).build(.{MyModule});
// Fast import: only HTTP + Core (skips SQLx, Redis, Kafka, etc.):
const http = zmodu.http; // Server, middleware, client, OpenAPI
const data = zmodu.data; // SQLx, Redis, ORM, Cache, Migrations
const sec = zmodu.security; // Auth, RBAC, API keys, Secrets
const obs = zmodu.observability; // Prometheus, Tracing, LoggingEach domain file is self-contained — importing zmodu.http does not compile sqlx or redis.
# Install Zig 0.16.0
brew install zig@0.16.0 # macOS
# or
apt install zig=0.16.0 # Linux// src/modules/user.zig
const std = @import("std");
const zigmodu = @import("zigmodu");
const UserModule = struct {
pub const info = zigmodu.api.Module{
.name = "user",
.description = "User management module",
.dependencies = &.{},
};
pub fn init() !void {
std.log.info("User module initialized", .{});
}
pub fn deinit() void {
std.log.info("User module cleaned up", .{});
}
};// src/main.zig
const std = @import("std");
const zigmodu = @import("zigmodu");
const user = @import("modules/user.zig");
pub fn main(init: std.process.Init) !void {
const allocator = init.gpa;
var modules = try zigmodu.scanModules(allocator, .{user});
defer modules.deinit();
try zigmodu.validateModules(&modules);
try zigmodu.startAll(&modules);
defer zigmodu.stopAll(&modules);
std.log.info("Application started!", .{});
}const Server = zigmodu.http_server.Server;
const Context = zigmodu.http_server.Context;
pub fn main(init: std.process.Init) !void {
var server = Server.init(init.io, init.gpa, 8080);
defer server.deinit();
try server.addRoute(.{
.method = .GET,
.path = "/health",
.handler = struct {
fn handle(ctx: *Context) anyerror!void {
try ctx.json(200, "{\"status\":\"ok\"}");
}
}.handle,
});
try server.start();
}# Start full stack (zigmodu + PostgreSQL + Redis)
docker compose up -d
# With Vault and Jaeger
docker compose --profile secrets --profile tracing up -dzigmodu/
├── src/
│ ├── root.zig # Public API (PRIMARY / ADVANCED / DEPRECATED)
│ ├── Application.zig # Application builder + lifecycle
│ ├── api/ # Public API types
│ │ ├── Module.zig # Module / Modulith structs
│ │ ├── Server.zig # HTTP server + router
│ │ └── Middleware.zig # Middleware framework
│ ├── core/ # Core framework
│ │ ├── Module.zig # ModuleInfo, ApplicationModules
│ │ ├── ModuleScanner.zig # Compile-time module scanning
│ │ ├── ModuleValidator.zig # Dependency validation
│ │ ├── ModuleInteractionVerifier.zig # Interaction model verification
│ │ ├── EventBus.zig # Type-safe event bus
│ │ ├── DistributedEventBus.zig # Cross-node event bus
│ │ ├── Lifecycle.zig # startAll/stopAll
│ │ ├── Time.zig # Monotonic time utility
│ │ ├── GrpcTransport.zig # gRPC service registry + proto parser
│ │ ├── KafkaConnector.zig # Kafka producer/consumer
│ │ ├── SagaOrchestrator.zig # Saga auto-compensation orchestrator
│ │ ├── DistributedTransaction.zig # 2PC + Saga transactions
│ │ ├── HealthEndpoint.zig # K8s liveness/readiness probes
│ │ ├── HotReloader.zig # File-watch hot reload
│ │ ├── PluginManager.zig # Dynamic plugin system
│ │ └── ...
│ ├── http/ # HTTP & API
│ │ ├── HttpClient.zig # HTTP client with pooling
│ │ ├── Idempotency.zig # Request deduplication middleware
│ │ └── OpenApi.zig # OpenAPI 3.x doc generator
│ ├── migration/ # Database migrations
│ │ └── Migration.zig # Flyway-style migration runner
│ ├── secrets/ # Secrets management
│ │ └── SecretsManager.zig # Multi-source secrets with Vault
│ ├── resilience/ # Resilience patterns
│ │ ├── CircuitBreaker.zig
│ │ ├── RateLimiter.zig
│ │ ├── Retry.zig
│ │ └── LoadShedder.zig
│ ├── metrics/ # Observability
│ │ ├── PrometheusMetrics.zig
│ │ └── AutoInstrumentation.zig
│ ├── tracing/ # Distributed tracing
│ │ └── DistributedTracer.zig
│ ├── security/ # Authentication & authorization
│ │ ├── SecurityModule.zig
│ │ ├── SecurityScanner.zig
│ │ ├── Rbac.zig
│ │ └── PasswordEncoder.zig
│ ├── tenant/ # Multi-tenancy
│ │ ├── TenantContext.zig
│ │ └── ShardRouter.zig
│ ├── sqlx/ # Database drivers
│ ├── redis/ # Redis client
│ ├── pool/ # Connection pool
│ ├── cache/ # Cache (LRU)
│ ├── scheduler/ # Task scheduler (Cron)
│ ├── messaging/ # Message queue + Outbox
│ ├── di/ # DI container
│ ├── config/ # Configuration (JSON/YAML/TOML)
│ ├── log/ # Structured logging
│ ├── test/ # Testing utilities
│ │ ├── ContractTest.zig # Pact-style contract testing
│ │ ├── IntegrationTest.zig
│ │ └── ModuleTest.zig
│ └── validation/ # Object validation
├── docs/ # Documentation
├── examples/ # Example projects
├── shopdemo/ # Full reference app (42 modules, 152 tables)
├── tools/zmodu/ # zmodu CLI code generator
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Full stack (PG + Redis + Vault + Jaeger)
└── .github/workflows/ci.yml # CI/CD pipeline
ZigModu grows with your application:
| Stage | DAU | Architecture | Key Capabilities |
|---|---|---|---|
| 1 | <1K | Monolith | Module + Lifecycle |
| 2 | 1K-10K | Vertical Scale | Events + Cache |
| 3 | 10K-100K | Multi-Instance | CircuitBreaker + RateLimiter |
| 4 | 100K-1M | Distributed | DistributedEventBus + Cluster |
| 5 | >1M | Platform | HotReload + Plugins + Kafka |
See Best Practices for detailed evolution guide.
# Build
zig build
# Run tests
zig build test
# Run example
zig build run
# Generate documentation
zig build docs
# Run benchmarks
zig build benchmark
# Format code
zig fmt src/
# Docker
docker compose up -d # Start full stack
docker compose --profile tracing up -d # With Jaeger| Example | Description |
|---|---|
| Basic | Module fundamentals |
| Event-Driven | Publish-subscribe patterns |
| Testing | Test utilities |
| HTTP Stress Test | Concurrent connections |
| Metaverse Creative | Creative demo |
| Distributed | Multi-node deployment |
| ShopDemo | Full e-commerce (42 modules, 790+ APIs) |
Contributions welcome! See CONTRIBUTING.md.
git clone https://github.com/yourusername/zigmodu.git
git checkout -b feature/my-feature
zig build test
git commit -m "feat: add feature"MIT License - see LICENSE for details.