Overview​

OxideAuth (codename: Ironstone) is a decentralized, multi-tenant Identity and Access Management platform built in Rust. It offloads the full complexity of authentication and authorization from individual services — allowing developers to focus on business logic rather than identity plumbing.

Unlike the previous Codativity-specific version, this is a general-purpose, self-contained IAM platform. Any organization can run it as their central auth service. It supports workspace-level multi-tenancy with complete data isolation, fine-grained RBAC with roles and permissions, stateless JWT tokens with a Redis-backed blacklist pattern, and a composable architecture of services, stores, and caches.

The codebase lives entirely in this repository — Rust source, database migrations, documentation, and Docker infrastructure all in one place.

Key Features​

• Multi-tenant workspaces — Three workspace types (GLOBAL, REGISTRY, STANDARD) with fully isolated data, roles, permissions, and configurations per tenant
• Fine-grained RBAC — Roles bundle permissions; memberships link accounts to workspaces and projects; policies constrain access contextually without granting new abilities
• Stateless JWT auth with blacklist — Tokens are validated by cryptographic signature with a fast Redis cache check for revoked tokens; database fallback ensures durability
• Polymorphic token system — Unified token table supports BLACKLIST (revoked JWTs), REFRESH (session renewal), API_KEY (machine-to-machine), and RESET_PASSWORD tokens
• Workspace-scoped login — Credentials (password, OAuth, SSO, API key) are scoped per workspace; login resolves the correct membership context for the JWT
• Embedded background worker — Tokio-spawned janitor task auto-prunes expired tokens from the database on a schedule
• AWS S3 & SES integration — Object storage for user uploads and transactional email delivery via AWS services

Architecture​

A layered, service-oriented Rust application backed by PostgreSQL and Redis:

All layers share an Arc<StoreManager> and Arc<CacheManager> via the ServiceFactory, with request-scoped services instantiated per-request to prevent state leakage.

Architecture Diagram​

[HTTP Request]
    ↓
Axum Handler (web/handlers/*.rs)
    ↓
CoreCtx Middleware → builds per-request context (membership, roles, permissions)
    ↓
Service Layer (core/services/*.rs) → business logic, hydration, authorization
    ↓
Store Layer (store/stores/*.rs) → sea-query + SQLx
    ↓
PostgreSQL / Redis

Data Model​

Core Entities​

RBAC Flow​

Account → Membership → Role → Permissions

A user's effective permissions are the union of all permissions granted by all roles assigned to their membership(s). Policies can only constrain — they never grant new abilities.

Workspace Types​

Token Architecture​

Stateless JWT with Blacklist​

The system uses stateless JWTs — the server trusts the token's cryptographic signature without a database lookup. To support logout and revocation, a blacklist pattern is used over a whitelist:

Every request: Signature check → Redis cache check (bl:{jti}) → Database fallback (if cache miss).

Token Types​

API Design​

All endpoints use HTTP POST with the action in the URL path (JSON-RPC style). This keeps sensitive data (tokens, credentials) in the request body and intentionally disables HTTP caching — a security requirement for real-time authorization.

Projects follow the same pattern at /projects/create, /projects/describe, etc.

Tech Stack​

Default RBAC​

When a new workspace is created, four default roles are seeded:

Permissions follow a resource:action convention (e.g., projects:create, members:invite, billing:manage). Over 20 default permissions are seeded across workspace, members, projects, roles, billing, and audit-log resources.

Development​

Prerequisites​

• Rust (latest stable)
• PostgreSQL 16
• Redis 7
• Docker & Docker Compose (optional, for infra)

Quick Start​

# Start PostgreSQL and Redis
docker compose up -d postgres redis

# Copy and fill in the config
cp ironstone/.cargo/config.example.toml ironstone/.cargo/config.toml

# Run dev migrations
cargo db-dev-run

# Start the dev server
cargo run --bin ironstone

The API starts on http://localhost:8000 by default. Health check at GET /health-check.

Project Structure​

oxideauth/
├── ironstone/              # Main Rust application
│   ├── src/
│   │   ├── main.rs         # Entrypoint, tokio runtime
│   │   ├── app.rs          # AppState, env config, init
│   │   ├── config.rs       # Config from environment
│   │   ├── web/            # Axum handlers, router, middleware, DTOs
│   │   ├── core/           # Services, models, traits, context, worker
│   │   ├── store/          # StoreManager, entities, stores, query traits
│   │   ├── cache/          # CacheManager, Redis, cache stores
│   │   ├── macros/         # Custom derive macros (filters)
│   │   ├── dev/            # Dev environment fixtures & seeding
│   │   └── utils/          # Shared utilities
│   └── sql/
│       ├── migrations/dev/ # Development schema migrations
│       ├── migrations/prod/# Production schema migrations
│       └── fixtures/       # Bootstrap data (accounts, workspaces, roles, etc.)
├── ironstone-macros/       # Procedural macro crate
├── docs/                   # Architecture & design documentation (24 docs)
├── docker-compose.yaml     # PostgreSQL + Redis infra
└── Dockerfile.dev          # Dev container with cargo-watch

Overview​

Raderbot is a single-binary Rust app on Actix Web. It maintains WebSocket streams to an exchange, stores incoming market data, runs algorithmic trading strategies, and exposes everything through a REST API. The architecture is trait-based: exchange adapters and storage backends can be swapped at runtime via the .env file or an API call.

• Dry-run by default — DRY_RUN=True routes all trading through a MockExchangeApi.
• Decoupled account & market layers — Account uses its own exchange API instance; market data can come from a different source.
• Pluggable storage — file system (default), MongoDB time-series, or InfluxDB.
• Dynamic exchange switching — an endpoint swaps the account adapter between Binance, BingX, and Mock without restart.

Module map​

src/
├── main.rs            # Entry point; Actix HttpServer, service registration
├── app.rs             # AppState — shared Arc<Mutex<...>> for bot, account, market, exchange
├── bot.rs             # RaderBot core + StrategyManager + async init loop
│
├── account/           # Position / TradeTx models, position lifecycle, adapter swap
├── algo/              # 12+ trading algorithms
├── analytics/         # Volume analysis (PriceVolume, TimeVolume, TradeVolume)
├── api/               # 5 route scopes: account, exchange, market, strategy, utils
├── exchange/          # Trait-based adapters: BinanceApi, BingXApi, MockExchangeApi + streams
├── market/            # Kline, Ticker, Trade structs + in-memory Market store
├── storage/           # FsStorage, MongoDbStorage, InfluxStorage behind StorageManager trait
├── strategy/          # Strategy loop, algorithm binding, SignalHandler, BackTest
└── utils/             # Channels, json helpers, time helpers

Root files​

Cargo.toml             # tokio, actix-web, reqwest, tokio-tungstenite, serde, ta, mongodb...
Makefile               # make build / dev / test / fix / clean / docs
docker-compose.yaml     # InfluxDB 2.7 (MongoDB commented out)
.env.example            # Exchange keys, DRY_RUN, storage backend, RUST_LOG
raderbot                # Prebuilt release binary
static/                 # Frontend assets
docs/                   # strategies.md
LICENSE.md              # MIT

Exchange layer​

Everything flows through a single async trait, ExchangeApi (src/exchange/api.rs):

#[async_trait]
pub trait ExchangeApi: Send + Sync {
    async fn get_account(&self) -> ApiResult<Value>;
    async fn open_position(&self, symbol, margin, leverage, side, price) -> ApiResult<Position>;
    async fn close_position(&self, position, close_price) -> ApiResult<TradeTx>;
    async fn get_kline(&self, symbol, interval) -> ApiResult<Kline>;
    async fn get_ticker(&self, symbol) -> ApiResult<Ticker>;
    fn get_stream_manager(&self) -> ArcMutex<Box<dyn StreamManager>>;
    // ...
}

Three implementations:

Streams are managed through a StreamManager trait (exchange/stream.rs). Each stream has metadata: id, URL, symbol, interval, start/last-update timestamps. Stream IDs follow <symbol>@kline_<interval> / <symbol>@ticker / <symbol>@trade.

Key detail from bot.rs: on startup the bot creates two exchange API instances — one for market data (hardcoded to BinanceApi), one for the account that can differ. When dry-run is on, the account gets a MockExchangeApi; otherwise it shares the market's BinanceApi or creates its own.

Market data​

Models live in src/market/:

The Market (market/market.rs) is the in-memory store — it receives data from active WebSocket streams via an async channel (MarketMessage in messages.rs) and supports range queries against both live and bootstrapped historical data.

Storage backends​

All implement the StorageManager trait. Selected at boot from .env:

Fallback behavior (from bot.rs): if Mongo or Influx fail to connect, the bot logs the error and falls back to FsStorage — no crash.

InfluxDB setup (docker-compose.yaml):

influxdb:
  image: influxdb:2.7
  ports: ["8086:8086"]
  environment:
    DOCKER_INFLUXDB_INIT_MODE: setup
    DOCKER_INFLUXDB_INIT_ORG: raderbot
    DOCKER_INFLUXDB_INIT_BUCKET: trade_data
    DOCKER_INFLUXDB_INIT_ADMIN_TOKEN: myadmintoken

Strategies & algorithms​

Lifecycle​

POST /new-strategy → bot.start_strategy(...) → picks an algorithm from src/algo/ → spawns a Strategy via tokio::spawn → tracks handle + settings in StrategyManager. A signal handler loop consumes SignalMessages and fires orders through the Account.

Available algorithms (src/algo/)​

Backtesting​

BackTest (strategy/backer.rs) replays KlineData over a strategy and produces a StrategySummary (PnL, trade count, win rate, etc.). Triggered via POST /run-back-test with symbol, interval, date range, and algorithm params. Uses the KlineData from the market's historical store.

Trade models​

• Position — symbol, order side (Buy/Sell), open price & time, quantity (margin × leverage / price), margin_usd, leverage, optional stop-loss and strategy ID. Uses uuid::v4 for IDs.
• TradeTx — close price, close time, computed profit (positive for winning trades on Buy, inverse for Sell), and linked source position with optional associated SignalMessage metadata.

REST API​

All endpoints under http://localhost:3000/api. Full request/response docs at the Postman collection — or download the collection JSON to import directly into Postman / Insomnia.

/api/market​

GET  /info                         Market summary
GET  /active-streams               Live stream metadata
POST /open-stream                  {stream_type, symbol, interval?}
POST /close-stream                 {stream_id}
POST /last-price                   {symbol}
POST /kline-data                   {symbol, interval}
POST /kline-data-range             {symbol, interval, from_ts?, to_ts?, limit?}
POST /ticker-data                  {symbol}
POST /trade-data                   {symbol, from_ts?, to_ts?, limit?}
POST /trade-volume-data            {symbol, ..., bucket_size? | time_interval?}

/api/account​

GET  /account-info
POST /set-exchange-api             {exchange, dry_run}  → swap Binance/BingX/Mock
GET  /active-positions
GET  /trades
POST /open-position                {symbol, margin, leverage, order_side, stop_loss?, strategy_id?}
POST /close-position               {position_id}
GET  /close-all-positions

/api/strategy​

POST /new-strategy                 {symbol, strategy_name, algorithm_params, interval, margin?, leverage?}
POST /stop-strategy                {strategy_id, close_positions?}
POST /stop-all-strategies          {close_positions?}
POST /set-params                   {strategy_id, params}
POST /change-settings              {strategy_id, settings}
GET  /active-strategies
GET  /historical-strategies
POST /historical-summary           {strategy_id}
POST /list-positions               {strategy_id}
POST /summary                      {strategy_id}
POST /info                         {strategy_id}
POST /run-back-test                {symbol, strategy_name, algorithm_params, interval, from_ts, to_ts, ...}

/api (root + static)​

GET /api                 → serves static/index.html
GET /static/*            → frontend assets (actix-files)

Getting started​

# Prereqs: Rust, cargo, make (Docker optional)
git clone https://github.com/subaquatic-pierre/raderbot.git
cd raderbot

# Configure
cp .env.example .env
# .env:
#   BINANCE_API_KEY=...
#   BINANCE_SECRET_KEY=...
#   DRY_RUN=True
#   STORAGE_TYPE=FS
#   RUST_LOG=info

# Build release binary
make build

# Run
./raderbot
# → Actix on 127.0.0.1:3000

# Dev mode (auto-reload on file changes)
make dev

Key .env values​

DRY_RUN=True              # True → MockExchangeApi (no real trades)
EXCHANGE_API=BINANCE      # BINANCE or BINGX
STORAGE_TYPE=FS           # FS | MONGO | INFLUX
MONGO_URI=mongodb://user:pass@localhost:27017/?authSource=admin
INFLUX_DB_HOST=http://localhost:8086
INFLUX_TOKEN=myadmintoken

Optional: InfluxDB for time-series metrics​

docker-compose up -d influxdb
# Update .env: STORAGE_TYPE=INFLUX, restart bot

Historical data​

For backtests and BootstrapKlineData/BootstrapTradeData requests, place CSV data from Binance public market data at:

~/Projects/BinanceData/
├── Kline/
│   ├── BTCUSDT-5m-2023-12.csv
│   └── ...
└── MarketTrade/
    ├── BTCUSDT-aggTrades-2020-01.csv
    └── ...

Source: data.binance.vision — download ZIP files from data/spot/monthly/klines/<SYMBOL>/<INTERVAL>/ (and aggTrades/ for trades). Extraction scripts in github.com/binance/binance-public-data.

Notes​

• Experimental — the bot is still in active development. Many features are undocumented or rough.
• Unix only — build targets Unix systems.
• Dry-run only by default — live trading requires DRY_RUN=False and a funded exchange API key.
• Market data required for orders — opening/closing positions requires a live last price from a stream or ticker call. Make sure the symbol has an active stream.
• Storage fallback — if Mongo or InfluxDB can't connect, the bot silently falls back to file-system storage.

Overview​

Sera Villas is a luxury booking platform showcasing four high-end vacation properties in Mallorca, Spain — Villa Escondido, Villa Lumina, Villa Vertice, and Villa Terra. The site combines the visual polish of a luxury brand with a complete booking engine that handles availability lookups, multi-step reservation flow, Stripe payment processing, and automated confirmation emails.

The platform connects to Uplisting (a property management system) for real-time availability and pricing, proxies all sensitive API calls through Next.js server-side routes to keep credentials secure, and uses Directus as a headless CMS for blog posts and page content.

Key Features​

• Full booking engine: Multi-step flow with guest details, Stripe payment, and automated confirmation emails
• Secure Uplisting proxy: All PMS API calls go through Next.js server routes — credentials never reach the browser
• Dynamic pricing: Cleaning fees, extra guest charges, taxes, weekly discounts (5%), and monthly discounts (10%)
• Availability calendars: Normalized calendar data from Uplisting displayed with custom UI components
• Multi-channel commissions: Tracks revenue across Airbnb, Booking.com, HomeAway, Google, and Direct channels
• SEO: Dynamic sitemap, per-page metadata, OpenGraph images, structured data for rich search results
• CDN delivery: Bunny CDN for static assets, CloudFront for Uplisting property photos
• Concierge mentions: All properties advertise premium services (private chefs, airport transfers, grocery pre-stocking)

Architecture​

A headless CMS + external PMS architecture:

The frontend is the sole consumer-facing service. Uplisting, Stripe, and AWS SES are integrated through Next.js API routes that proxy requests — keeping API keys server-side and avoiding browser CORS issues.

Frontend — Next.js App Router with Tailwind & shadcn/ui​

Built with Next.js 15 App Router, Tailwind CSS, and shadcn/ui (New York style, Neutral base). The site uses 60+ custom components and 9 context providers for booking state, villa data, theming, notifications, and viewport management.

Pages​

• Home — Hero section, villa listing grid, testimonials, blog highlights, Instagram feed
• Villas — Listing page with all four properties
• Villa Detail — Individual villa pages with photo gallery (Embla carousel), features grid, room layouts, map, amenity icons, and booking panel
• Booking — Multi-step flow: date selection → guest details → price breakdown → payment
• Booking Confirmation — Success page with booking summary
• Blog — CMS-managed articles from Directus
• About Us — Brand story and team
• Privacy / Cookie / Terms — Legal pages

Booking Engine​

The booking flow is a polished multi-step experience:

1. Date selection — Availability calendar powered by Uplisting data
2. Guest details — Contact information and guest count
3. Price breakdown — Dynamic pricing with cleaning fees, extra guest charges, taxes, and weekly/monthly discounts
4. Stripe checkout — Secure card payment processing
5. Confirmation — Success page with automated AWS SES email

CMS — Directus​

Directus manages blog posts, CMS pages, and SEO metadata. Content is fetched via the @directus/sdk and served through Next.js ISR. Static assets are stored in a Hetzner S3 bucket and delivered through Bunny CDN at cdt-sera-villas.b-cdn.net for fast global delivery.

Third-Party Integrations​

Multi-Channel Commission Tracking​

Uplisting provides commission data across booking channels: Airbnb (18.34%), Booking.com (15%), HomeAway (8%), Google (6%), and Direct (0%) — allowing the business to track profitability by channel.

Tech Stack​

Overview​

RAK NYE CarPass is a production-scale parking and access management system built for the Ras Al Khaimah New Year's Eve festival on Al Marjan Island, UAE. It manages every aspect of vehicle access to the event area — from visitor car pass registration and hotel quota management to real-time ANPR (Automatic Number Plate Recognition) camera integration and live parking occupancy dashboards.

The system handles 10 parking locations across Al Marjan Island with traffic flow balancing, WhatsApp + SMS communication, barcode/QR entry passes, and a dedicated public display screen showing real-time parking availability. Built as a polyglot microservices system spanning TypeScript, C# (.NET), and Python.

Key Features​

• ANPR camera integration: Direct Hikvision camera connection with real-time plate registration and allow-list management
• Multi-format scan parsing: XML, JSON, BSON, and multipart/form-data with robust fallback handling
• 10 parking locations: Jais, Yanas, Dhayah, Mega, Marjan1-4, VIP1, VIP2 — each with live occupancy tracking
• Traffic flow balancing: Duplicate scan events across related locations for accurate occupancy counts
• Hotel quota system: Per-hotel vehicle pass limits for guest management
• Barcode/QR entry: PDF certificates with embedded QR codes for access passes
• Live parking stats: Real-time occupancy dashboards with ApexCharts and count-up animations
• Mobile scanner: HTML5 QR scanner for entry/exit checkpoint staff
• WhatsApp + SMS: Twilio templated messaging with automatic fallback for undelivered WhatsApp messages
• Multi-language: Full Arabic/English bilingual site with separate logos and RTL layout

Architecture​

A five-service polyglot system with OxideAuth for authentication:

www — Public Site​

Built with Next.js 16 App Router and MUI v7, supporting full Arabic/English bilingual with RTL layout using react-intl / next-international. The site features the Abu Dhabi Media font and separate Arabic and English logos.

Pages​

• Car Pass Registration — Vehicle and driver registration form
• Update CarPass — Modify existing registrations
• Parking Registration — Parking pass purchase flow
• Marjan Island Access — Event venue information
• Celebration Guide — PDF event guides and schedules
• Visitor Survey — Post-event feedback
• Live Parking Updates — Real-time occupancy display
• Public Display Screen — Large-format parking availability board for venue entry points

dashboard — Admin Panel​

The admin dashboard uses role-based views: Admin, Hotel, and Stats roles. Features include:

• Car pass management — View, approve, and manage all registrations
• Hotel/quota management — Per-hotel vehicle pass quotas
• Live parking stats — ApexCharts dashboards with count-up animations
• Scan log viewer — Real-time entry/exit event logs
• Barcode/QR scanner — Desktop and mobile scanning interfaces
• Puck CMS — @measured/puck drag-and-drop page builder for custom admin layouts
• Token management — Secure access token administration

anpr-service — .NET 8 Camera Integration​

The ANPR service connects directly to Hikvision iDS-TCM403-B cameras for real-time license plate recognition. It handles:

• Scan intake — Receives camera scan data via XML/JSON/multipart
• Plate registration — Programmatically adds authorized plates to camera allow lists
• Traffic flow logic — Duplicates scan events across related parking locations (e.g., Marjan1 entry → Yanas exit) for accurate occupancy counts across the 10 parking zones
• WhatsApp + SMS — Twilio-powered messaging with automatic SMS fallback when WhatsApp delivery fails
• Message callbacks — Delivery status tracking for sent messages

etl — Python Data Pipeline​

A batch ETL pipeline migrates data between database instances. It parses scan data from multiple formats (XML for Hikvision cameras, JSON, BSON, gate-specific) with configurable batch sizes and handles bulk hotel account imports from CSV files.

Tech Stack​

Overview​

Maven Platform is a specialized Bill of Quantities (BOQ) management system built for the construction and procurement industry. It handles the entire BOQ workflow — from project creation and work order generation to work item classification, checklist management, and professional document export.

What sets Maven apart is its .NET BOQ Exporter — a dedicated microservice that generates commercial-grade multi-sheet Excel (XLSX) and PDF documents with professional formatting: table of contents, preambles, section sheets, page numbers, watermarks, and A4 print layouts. This is powered by Aspose.Cells, a licensed Excel generation engine.

Key Features​

• Five-role RBAC: SuperAdmin, TeamManager, TeamLeader, QS, OfficeManager with entity-level permissions
• BOQ Export Engine: Commercial-grade XLSX/PDF generation with Aspose.Cells — multi-sheet, table of contents, watermarks, A4 formatting
• TanStack React Table: Performant data grids with sorting, filtering, and pagination for large BOQ datasets
• Flexible query protocol: $and/$or JSON filters, population, pagination, fuzzy search, soft delete — all through a clean REST API
• Drag-and-drop editing: DnD Kit for interactive reordering of work items and sections
• QR code tracking: Generated QR codes on uploads and documents for traceability
• Dual deployment mode: Kubernetes for staging, bare-metal VMs via systemd for production (with Cloudflare load balancing)

Architecture​

A polyglot three-service system with OxideAuth for authentication:

The API uses five role types (SuperAdmin, TeamManager, TeamLeader, QS, OfficeManager) with fine-grained permissions on every entity. Auth is delegated to OxideAuth.

www — Dashboard​

The frontend is a Next.js App Router application with MUI v7, MUI X Pro (Tree View), and TanStack React Table for performant data grids. It supports English and Arabic with full RTL layout.

Dashboard Sections​

• Projects & Clients — Project lifecycle management and client relationships
• Work Orders & BOQs — The core BOQ workflow
• Work Items — Classified line items within BOQs
• Templates — Reusable BOQ templates for standardization
• Checklists — QA/QC checklists with response tracking
• Section Editor — BOQ section organization
• Suppliers, Tenders & Bids — Procurement workflow
• Invoice — Billing and payment tracking
• Variable Option Sets — Dynamic pricing configuration
• Settings & Users — Platform administration

Rich Content Editing​

The dashboard includes TipTap for rich text editing (with color, highlighting, images, alignment) and DnD Kit for drag-and-drop reordering. Puck CMS (@measured/puck) provides a visual page builder for custom layouts.

api — Express.js Backend​

The Express.js API uses MikroORM for database access with 22 entity models and 22+ route sets. A flexible query protocol supports $and/$or JSON filters, population, pagination, fuzzy search, and soft deletion — giving the frontend powerful querying without exposing SQL.

All routes enforce OxideAuth-based RBAC with permissions like maven.boq.create and maven.ui.admin. The API also handles file uploads with drag-and-drop support, QR code generation for document tracking, and integration with the .NET export engine.

BOQExporter — .NET 8 Export Engine​

The BOQ Exporter is a .NET 8 ASP.NET Core Minimal API that uses Aspose.Cells (licensed) to generate professional BOQ documents:

• Multi-sheet XLSX: Cover page, table of contents, preambles, individual section sheets, summary sheet
• Custom formatting: Fonts, colors, borders, print area, A4 portrait, page numbers, watermarks
• PDF generation: Via SkiaSharp for non-editable distribution
• Storage integration: Uploads generated files to Hetzner S3 and returns download URLs

Endpoints: POST /export-boq, POST /export-section, GET /ping. The production Docker image includes LibreOffice Calc for server-side document format conversion.

Tech Stack​

Overview​

Event Hoster is a complete event management platform designed for conference organizers. Originally built as a demo for a 3-day conference in Ras Al Khaimah, UAE, it has evolved into a full-featured system that handles every aspect of running a professional event — from the public marketing website to attendee check-in at the venue.

The platform supports English and Arabic (with RTL layout), role-based access control across seven user roles, and integrations for QR-based check-in, PDF certificate generation, ticket management, real-time messaging, and attendee feedback collection.

Key Features​

• Seven-role RBAC: admin, member, author, organizer, speaker, visitor — each with custom dashboard menus and permissions
• QR-based check-in: Camera scanner at venue entrances + QR generation on tickets and certificates
• PDF certificate generation: Dynamic certificates with attendee name, session hours, and verifiable QR codes
• Multi-day agenda: 3-day schedule with hall-based filtering (A, B, C)
• Bilingual support: Full English and Arabic interface with RTL layout and flag-based language switcher
• Countdown timer: Eye-catching landing page countdown to event date
• Feedback collection: 12-question satisfaction survey for post-event analytics
• Notification system: In-app notifications for profile updates, registrations, and abstract reviews

Architecture​

A three-frontend split with a shared Strapi CMS backend:

This three-app split creates clean separation: the public site is optimized for visitors browsing event details, while the dashboard is a full-featured SPA for organizers and attendees.

www — Public Event Website​

The public-facing site serves as the conference's digital storefront. Built with Next.js 13 Pages Router, it uses MUI v5 for the component library and react-intl for bilingual English/Arabic with RTL support.

Landing page features a countdown timer to the event date. The agenda view displays a 3-day schedule filterable by hall (A/B/C). Speaker profiles show headshots and bios, and visitors can register, purchase tickets via Stripe, and verify certificates through a public lookup tool.

dashboard — Admin & User Application​

The dashboard is a comprehensive management interface built with Next.js, Redux Toolkit for state, and FullCalendar for scheduling. Seven user roles each get customized navigation menus: admin, member, author, organizer, speaker, and visitor.

Dashboard Capabilities​

• QR code scanner — Camera-based attendee check-in using html5-qrcode
• Schedule management — FullCalendar with drag-and-drop event CRUD
• Certificate generation — Dynamic PDF certificates with embedded QR codes using pdf-lib
• Ticket generation — QR-coded entry tickets for attendees
• Chat/messaging — Real-time messaging between users with emoji picker
• Attendance tracking — Per-day, per-hall records with online/in-person status
• Blog management — CRUD for news articles
• Registration management — Attendee approval and session abstract review

Backend — Strapi CMS​

Strapi manages all content through a rich data model: Event, Profile, Abstract, Blog, AttendRecord, FeedbackForm, Message, Notification, TicketType, and ProfileLog collections. Custom API endpoints provide profile lookups, admin queries, and attendance record operations.

Files are stored in Azure Blob Storage — particularly important for generated certificates and tickets that need durable, scalable storage. Emails are delivered through SendGrid in production, with a local MailDev instance for development testing.

Tech Stack​

Quick index​

basic-webserver​

What it builds​

A minimal AWS environment: a VPC with public subnets, security groups, an SSH key pair, and an EC2 instance bootstrapped with Nginx via user-data. The entry-point lab — used to learn Terraform + AWS fundamentals.

File map​

basic-webserver/
├── vpc.tf          # VPC module (terraform-aws-modules/vpc/aws ~> 5.0)
├── sg.tf           # Security groups for HTTP (80) + SSH (22)
├── ec2.tf          # EC2 instance + TLS private key + key pair
├── main.tf         # Provider + backend config
├── variables.tf
└── output.tf

How it works​

• VPC (vpc.tf) — uses the official terraform-aws-modules/vpc/aws module (v5). Two public subnets across us-east-1a and us-east-1b, one private subnet. No NAT gateway (cost-conscious). DNS hostnames and support enabled.
• Security group (sg.tf) — ingress for port 80 (HTTP, 0.0.0.0/0) and port 22 (SSH, 0.0.0.0/0), standard egress all.
• EC2 (ec2.tf) — looks up the latest Ubuntu 22.04 AMI via data source, generates a 4096-bit RSA key pair with the tls_private_key resource, writes the private key to keys/<name>.pem with mode 0600, and launches the instance in the first public subnet. User-data installs Nginx and writes a Hello World from Terraform! index page.

Quick start​

cd basic-webserver/
terraform init
terraform plan
terraform apply

# SSH in (key written to keys/ directory)
ssh -i keys/my-key.pem ec2-user@$(terraform output -raw public_ip)
# Or open the public IP in a browser to hit Nginx

eks​

What it builds​

A production-ready EKS cluster with managed node groups, IAM Roles for Service Accounts (IRSA) using the new pod identity agent, RBAC with three access tiers, and essential add-ons: AWS Load Balancer Controller, Cluster Autoscaler, and Metrics Server. Also includes example app manifests for HPA scaling tests and a Next.js static build deploy recipe.

File map​

eks/
├── eks.tf          # EKS cluster + IAM role + add-ons (pod identity, network flow monitoring)
├── nodes.tf        # Managed node group (SPOT, t3.large, 1-10 nodes)
├── vpc.tf          # Custom VPC (no module — raw aws_vpc, aws_subnet, etc.)
├── role.tf         # IAM roles for service accounts (ALB controller, external-dns, etc.)
├── trust.tf        # OIDC trust relationship for IRSA
├── rbac.tf         # Three ClusterRoleBindings: admins, developers, viewers
├── users.tf        # IAM users grouped into eks-admins / eks-developers / eks-viewers
├── autoscaler.tf   # Cluster Autoscaler via Helm + pod identity association
├── lbc.tf          # AWS Load Balancer Controller via Helm
├── metrics.tf      # Metrics Server via Helm
├── apps/           # Example k8s manifests (HPA demo, Next.js static)
├── policies/       # IAM policy JSON documents
├── main.tf         # Provider + backend
├── providers.tf    # Provider aliases (aws + kubernetes + helm)
├── variables.tf
├── output.tf
└── version.tf

How it works​

• EKS control plane (eks.tf) — cluster with public endpoint, private-only subnet placement, API authentication mode, bootstrap admin permissions, and two add-ons: aws-network-flow-monitoring-agent and eks-pod-identity-agent. The pod identity agent enables EKS Pod Identity associations (the newer replacement for IRSA via OIDC).
• Node group (nodes.tf) — single managed node group using SPOT capacity, t3.large instances, 1 desired / 0 min / 10 max. Lives in private subnets. lifecycle { ignore_changes = [scaling_config[0].desired_size] } so the autoscaler can adjust the count without Terraform drift. Commented-out launch template shows how to add custom user-data.
• RBAC (rbac.tf) — three groups mapped to ClusterRoles: eks-admins → cluster-admin, eks-developers → edit (in development namespace), eks-viewers → view. IAM users are assigned to groups in users.tf.
• Cluster Autoscaler (autoscaler.tf) — installed via Helm (v9.37.0, kube-system namespace). Uses an EKS Pod Identity association — the autoscaler service account is mapped to an IAM role with a custom policy (policies/AWSClusterAutoScaler.json) via aws_eks_pod_identity_association. This is the newer, cleaner approach vs. OIDC IRSA.
• Load Balancer Controller (lbc.tf) — Helm install of aws-load-balancer-controller. Provisions ALBs/NLBs automatically from Kubernetes Ingress resources.
• Metrics Server (metrics.tf) — Helm install. Required for HPA and kubectl top.

Quick start​

cd eks/
terraform init
terraform plan
terraform apply

# Grab kubeconfig
aws eks update-kubeconfig --name $(terraform output -raw cluster_name)

# Trigger HPA scaling test
kubectl apply -f apps/app-hpa/
kubectl port-forward -n example svc/myapp 8080:8080
curl http://localhost:8080/api/cpu?index=44

# Deploy a Next.js static build to S3 + CloudFront
aws s3 sync out/ s3://$(terraform output -raw bucket_name) --delete
aws cloudfront create-invalidation \
  --distribution-id $(terraform output -raw cloudfront_id) \
  --paths "/*"

TODO (from README)​

• Add L4 LoadBalancer with Nginx Ingress
• Install cert-manager for cluster-wide SSL

gitops​

What it builds​

Bootstraps ArgoCD onto an EKS cluster and configures an ApplicationSet that discovers and syncs applications from a Git repository. Also sets up Sealed Secrets for encrypting sensitive values (Docker registry pull secrets) that can be safely committed to Git. Includes SSH-based private repo authentication for ArgoCD.

File map​

gitops/
├── argocd.tf       # ArgoCD Helm install + ApplicationSet + SSH repo credentials
├── ns.tf           # Project namespaces (via kubernetes_namespace_v1)
├── secrets.tf      # Sealed Secrets controller (Helm)
├── secrets.md      # Step-by-step for encrypting docker config with kubeseal
├── providers.tf
├── variables.tf
├── apps/           # Example ArgoCD Application manifests
├── gitops-example/ # Reference repo structure: environments/<env>/<app>/
└── Makefile

How it works​

• ArgoCD install (argocd.tf) — deploys via Helm (chart argo-cd v10.1.4). Server gets --insecure flag for HTTP access during development.
• SSH repo credentials — a kubernetes_secret_v1 labeled argocd.argoproj.io/secret-type: repository stores an SSH private key (read from disk at secrets/git_ssh.key). ArgoCD uses this to clone the GitOps repo over SSH without a username/password.
• ApplicationSet — a kubernetes_manifest that defines a Git directory generator. Anything under environments/*/* in the GitOps repo becomes an ArgoCD Application with automated sync (prune + self-heal enabled). Naming convention: {{path[1]}}-{{path[2]}}.
• Sealed Secrets (secrets.tf) — deploys the Bitnami Sealed Secrets controller via Helm. The secrets.md file walks through encrypting a Docker config.json using kubeseal so private registry pull credentials can live in Git safely. The encrypted secret is then managed by Terraform.

Quick start​

# Prerequisite — install Sealed Secrets controller
helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets
helm repo update
helm install sealed-secrets sealed-secrets/sealed-secrets \
  --namespace sealed-secrets --create-namespace

# Encrypt a docker config secret for Git
kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson \
  --namespace=project \
  --dry-run=client -o yaml > local-regcred.secret.yaml

kubeseal --format yaml < local-regcred.secret.yaml > docker-regcred.yaml \
  --controller-namespace sealed-secrets \
  --controller-name sealed-secrets

# Deploy gitops stack
cd gitops/
terraform init
terraform apply

sre​

What it builds​

A full Grafana LGTM observability stack: Grafana for dashboards, Loki for log aggregation, Mimir for long-term metrics storage, and Grafana Alloy as the telemetry collector (metrics + logs). Plus Metrics Server and kube-state-metrics. Designed to run locally on Minikube with CSI-hostpath storage, or on EKS with S3 object storage for Loki chunks/ruler and Mimir blocks/alerts/ruler.

File map​

sre/
├── grafana.tf      # Grafana Helm install (v12.7.2)
├── loki.tf         # Loki Helm install (v18.5.0) — S3-backed
├── mimir.tf        # Mimir distributed Helm install (v6.2.0) — S3-backed
├── alloy.tf        # Alloy Helm install (v1.10.1) — River config from templates
├── metrics_server.tf    # Metrics Server Helm install
├── state_metrics.tf     # kube-state-metrics Helm install
├── s3.tf           # 5 S3 buckets: loki_chunks, loki_ruler, mimir, mimir_alert, mimir_block, mimir_ruler
├── secrets.tf      # S3 credentials as k8s secrets for Loki + Mimir
├── ns.tf           # Namespaces: monitoring, loki, mimir
├── node_init.tf    # Node label bootstrap
├── locals.tf       # Shared locals (AWS region, namespace refs)
├── values/         # Helm value overrides + Alloy River config templates
│   ├── grafana.yaml
│   ├── loki-ss.yaml
│   ├── mimir.yaml
│   ├── alloy.yaml
│   └── alloy/      # River config: discovery.river, metrics.river, logs.river, loki.river
├── providers.tf
├── variables.tf
├── version.tf
└── Makefile        # Port-forward shortcuts

How it works​

• Alloy (alloy.tf) — the most interesting piece. Uses templatefile() to compose Alloy's River configuration from four template files: discovery.river (Kubernetes service discovery), metrics.river (scrape → Mimir), logs.river (collect → Loki), and loki.river (self-monitoring). The assembled config is passed as a Helm value. Alloy replaces the older Grafana Agent as the unified collector — one binary for metrics, logs, and traces.
• Loki (loki.tf) — deployed with S3 storage backend for chunks and ruler. Values are templated with bucket names, AWS region, and credentials. Depends on the S3 buckets being created first.
• Mimir (mimir.tf) — the mimir-distributed chart (v6.2.0-weekly.402). Uses four S3 buckets (blocks, alertmanager, ruler, and a general bucket). Also depends on an S3 credentials secret.
• Grafana (grafana.tf) — pre-configured with Loki and Mimir as data sources via templatefile. The grafana.yaml values file references the cluster-internal service endpoints for both backends.
• S3 buckets (s3.tf) — five buckets for Loki (chunks, ruler) and Mimir (blocks, alertmanager, ruler, general). Forces S3 over local storage when connected to AWS; defaults to CSI-hostpath volumes on Minikube.

Local dev (Minikube)​

# Start 4-node cluster with CSI storage and Flannel CNI
minikube start \
  --nodes=4 \
  --cni=flannel \
  --addons=volumesnapshots,csi-hostpath-driver \
  --extra-config=apiserver.storage-roles=true

# Enable CSI as default storage class
minikube addons enable volumesnapshots
minikube addons enable csi-hostpath-driver
minikube addons disable storage-provisioner
minikube addons disable default-storageclass
kubectl patch storageclass csi-hostpath-sc \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Deploy the stack
cd sre/
terraform init
terraform apply

# Port-forward UIs
make port-forward
# Grafana  → http://localhost:5000
# Alloy UI → http://localhost:5001
# Mimir UI → http://localhost:5002

Helm in-place updates​

helm upgrade loki grafana/loki \
  --namespace monitoring \
  --reuse-values \
  --set loki.storage.s3.insecure=true

static-website​

What it builds​

A secure, CDN-accelerated static site: S3 bucket with static website hosting, CloudFront distribution with Origin Access Control (OAC), ACM SSL certificate, and Route53 DNS alias. The S3 bucket policy restricts access to CloudFront only (no public-read ACLs).

File map​

static-website/
├── s3.tf           # S3 bucket + versioning + public access block + website config + bucket policy
├── cloudfront.tf   # CloudFront distribution + OAC + custom error response
├── acm.tf          # ACM certificate + DNS validation
├── dns.tf          # Route53 alias record → CloudFront
├── providers.tf
├── variables.tf
├── output.tf
├── version.tf
├── apps/           # Static site content (js, css, html)
├── scripts/        # S3 sync + CloudFront invalidation helpers
└── Makefile

How it works​

• S3 (s3.tf) — bucket with versioning enabled, full public access block (no ACLs, no public policies), website config pointing to index.html / error.html. The bucket policy grants s3:GetObject only to the CloudFront distribution ARN via AWS:SourceArn condition. A commented-out legacy policy shows the older public-read approach that this replaced.
• CloudFront (cloudfront.tf) — distribution with Origin Access Control (OAC, not the legacy OAI), sigv4 signing, HTTPS redirect, and a custom 404 → 200 error response pointing to /index.html (SPA-friendly). Viewer certificate uses the ACM cert from acm.tf.
• ACM (acm.tf) — certificate created in us-east-1 (required for CloudFront) with DNS validation via Route53.
• Route53 (dns.tf) — alias A record pointing infra.<domain> to the CloudFront distribution.

Quick start​

cd static-website/
terraform init
terraform apply

# Sync content and bust cache
aws s3 sync ./apps/ s3://<project>-bucket --delete
aws cloudfront create-invalidation --distribution-id <id> --paths "/*"

serverless-api​

What it builds​

A REST API on API Gateway backed by Python Lambda functions. Uses the mewa/apigateway-cors module for CORS handling. Lambda handlers are skeleton methods — fill in your business logic.

File map​

serverless-api/
├── main.tf         # Root: wires api + lambda modules together
├── variables.tf
├── outputs.tf
├── api/            # API Gateway module (REST API, resources, methods, integrations)
├── assets/         # Cloud architecture diagram
├── lambda/
│   └── handlers/
│       └── http_methods.py   # Skeleton handlers: list, get, post, put, delete
└── lambda module/  # Lambda function + IAM role + permission

How it works​

• Modular design (main.tf) — the API and Lambda are separate Terraform modules. The root main.tf wires them by passing the API's execution ARN into the Lambda module, and each Lambda's invoke ARN back into the API module. CORS is handled by the mewa/apigateway-cors/aws community module (v2.0.1), applied to both the root resource and the /resource path.
• Endpoints — six methods across two resources:

• Lambda handlers — http_methods.py exports a @app.route decorator pattern. Responses use a Response.format class method for consistent JSON structure. No implementation — just the skeleton ready for business logic.
• Providers — uses AWS provider ~> 4.0.0, plus random and archive for Lambda packaging.

Quick start​

cd serverless-api/
cp terraform.tfvars.example terraform.tfvars   # fill in domain_name, tags
terraform plan -out plan
terraform apply

# Note: DNS propagation can take a couple of hours. If the first apply fails
# due to resource creation ordering, retry — it usually works on the second run.

aws-ecs-ci-cd​

What it builds​

A full CI/CD infrastructure for a decoupled full-stack application: a Django GraphQL API backend on ECS Fargate behind an ALB with Auto Scaling, and a React frontend on S3/CloudFront. Both are deployed by independent AWS CodePipelines triggered from separate GitHub repos via CodeStar Connections. Includes a custom VPC, SSL via ACM, Route53 DNS, ECR image repository, and ALB access logs streamed to S3 (queryable via Athena).

File map​

aws-ecs-ci-cd/
├── main.tf              # All resources (monolith — VPC, ECS, CodePipeline, S3, CloudFront, Route53)
├── variables.tf
├── terraform.tfvars.example   # Extensive var file: repos, ECR URI, domain, secrets, VPC CIDRs
├── api/                 # Backend ECS task def + service + ALB config
├── frontend/            # Frontend S3 + CloudFront config
├── pipelines/           # CodePipeline definitions + buildspec files
│   ├── api/             #   Backend pipeline (build Docker → push ECR → deploy ECS)
│   └── frontend/        #   Frontend pipeline (build React → sync S3 → invalidate CloudFront)
└── readme/              # Screenshots + detailed how-to guides for every prerequisite

How it works​

• Decoupled pipelines — two independent CodePipelines. Pushing to the backend GitHub repo triggers the API pipeline (build Docker image, push to ECR, deploy to ECS). Pushing to the frontend GitHub repo triggers the frontend pipeline (build React, sync to S3, invalidate CloudFront). Each has its own buildspec with testing hooks.
• ECS backend — Fargate launch type, ALB with Auto Scaling Group. The ECR repository URI is passed via api_ecr_app_uri variable. Docker build secrets (DB credentials, Django secret key, AWS keys, Docker Hub credentials) are injected at build time via build_secrets map.
• Networking — VPC with 2 public + 2 private subnets across us-east-1a and us-east-1b, NAT gateway, internet gateway. All resources are in us-east-1.
• DNS + SSL — Route53 hosted zone with www → root redirect. ACM certificate for HTTPS. ALB access logs go to S3 with Athena partitioning for querying.
• Prerequisites are involved — the README has dedicated sections for each: Route53 domain, ACM certificate, Terraform backend S3 bucket, GitHub repos for frontend and backend (sample repos linked: react-apollo and django-graphql), CodeStar connection, ECR repository, RDS Postgres DB, and AWS access key credentials.

Quick start​

cd aws-ecs-ci-cd/
cp terraform.tfvars.example terraform.tfvars   # fill in ALL variables
terraform init
terraform apply
# Push to either repo's main branch → pipeline triggers automatically

pwa-ci-cd​

What it builds​

Infrastructure and GitHub Actions workflows for a Progressive Web App with staging and production environments. Uses S3 + CloudFront for hosting, ACM for SSL, Route53 for DNS (including www → bare redirect). Terraform is isolated in a terraform/ subdirectory, separate from the app code.

File map​

pwa-ci-cd/
├── terraform/               # Isolated Terraform config (separate from app code)
├── app/                     # PWA application source
├── assets/                  # Cloud architecture diagram
├── .github/workflows/       # CI/CD actions
│   ├── test.yml             #   Runs on push to dev
│   ├── deploy-staging.yml   #   Tests + deploys to staging.domain.com on push to staging
│   └── deploy-prod.yml      #   Tests + deploys to domain.com on push to main
├── README.md
└── README.md.pwa-pipeline   # Pipeline-specific docs

How it works​

• Three-branch Git workflow — dev (test only) → staging (test + deploy to staging) → main (test + deploy to production). Each merge triggers the corresponding GitHub Action.
• Dual environments — two sets of S3 buckets and CloudFront distributions: one for staging (staging.domain.com), one for production (domain.com). The www → root redirect bucket is a third S3 bucket configured for website redirect.
• GitHub Actions — uses AWS CLI in the runner to sync app/ to S3 and invalidate CloudFront. Secrets (AWS keys, bucket IDs, distribution IDs) come from Terraform outputs, manually set in GitHub repo settings.
• Known issue — the CloudFront distribution for the www → root redirect bucket hits an upstream Terraform AWS provider bug (#24332). The origin must be manually patched in the AWS Console to point to the S3 website endpoint (bucket.s3-website-us-east-1.amazonaws.com) instead of the REST endpoint.

Quick start​

cd pwa-ci-cd/terraform/
terraform init
terraform plan -out plan
terraform apply

# Grab outputs and set in GitHub Secrets:
#   MAIN_CLOUDFRONT_DISTRIBUTION_ID  → main_cloudfront_dist_id
#   MAIN_S3_BUCKET_ID                → main_s3_bucket_id
#   STAGING_CLOUDFRONT_DISTRIBUTION_ID → staging_cloudfront_dist_id
#   STAGING_S3_BUCKET_ID             → staging_s3_bucket_id
#   + AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

# Fix the redirect bucket origin manually in AWS Console (see known issue above)

Local SRE dev setup​

Used by the sre/ lab; also referenced in the main README:

minikube start \
  --nodes=4 \
  --cni=flannel \
  --addons=volumesnapshots,csi-hostpath-driver \
  --extra-config=apiserver.storage-roles=true

minikube addons enable volumesnapshots
minikube addons enable csi-hostpath-driver
minikube addons disable storage-provisioner
minikube addons disable default-storageclass

kubectl patch storageclass csi-hostpath-sc \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Overview​

Risk-V is not a software project — it is a structural, educational microarchitecture study of a complete 5-stage pipelined RISC-V (RV32I) processor built in Logisim-evolution, a digital logic simulator. Every wire, every gate, and every pipeline register is visible and step-through-able.

The design covers the full classic 5-stage pipeline — Instruction Fetch, Decode, Execute, Memory Access, and Writeback — with hardware implementations of load-use hazard detection and stalling, operand forwarding (bypassing from EX/MEM and MEM/WB stages), and branch/jump resolution with pipeline flushes. An in-progress 4-way set-associative cache subsystem rounds out the memory hierarchy.

Complemented by a 22-page MkDocs Material documentation site and a Python-based automated test runner that validates 14 test suites against expected register state, the project is designed as both a reference implementation and a teaching tool.

Key Features​

• Complete 5-stage RISC-V RV32I CPU: IF (Instruction Fetch) → ID (Decode + Register File) → EX (Execute + ALU) → MEM (Memory Access) → WB (Writeback)
• Hardware Hazard Controller: Formal boolean logic for load-use hazard detection — LoadUseHazard = ID_EX_MemRead AND (ID_EX_rd != 0) AND (ID_EX_rd == IF_ID_rs1 OR ID_EX_rd == IF_ID_rs2) — triggering 1-cycle stalls with PC/IF_ID writes disabled
• Operand Forwarding: Forwarding paths from EX/MEM and MEM/WB pipeline registers back to the ALU inputs, eliminating unnecessary stalls
• Branch and Jump Resolution: Control hazards handled with pipeline flushes when branches are taken; jump target computed in the Decode stage
• Full structural visibility: Every component built from Logisim primitives (AND/OR/NOT gates, multiplexers, registers) — no hidden abstractions
• 14 test suites: Automated testing via Logisim CLI covering alignment, branches, cache, control signals, CSR operations, pipeline flush behavior, multiply, and SLT instructions
• In-progress cache subsystem: 4-way set-associative cache with pseudo-LRU replacement, cache FSM with write-through/write-back policies
• RISC-V toolchain integration: riscv64-unknown-elf-as assembler integration via compile_logisim.sh that converts assembly listings to Logisim-compatible hex ROM files
• Comprehensive documentation: MkDocs Material site with detailed write-ups on pipeline timing, hazard theory with truth tables, ALU control decoding, and component-by-component specifications

Architecture​

CPU Datapath​

┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│   IF    │──▶│   ID    │──▶│   EX    │──▶│   MEM   │──▶│   WB    │
│ PC+IMem │   │ Ctrl+RF │   │ ALU+Fwd │   │ DMem+Al │   │ WB Mux  │
└─────────┘   └─────────┘   └─────────┘   └─────────┘   └─────────┘
     │             │             │             │
  IF/ID reg     ID/EX reg     EX/MEM reg    MEM/WB reg
     │             │             │             │
     └──── Stall/Flush logic (Hazard Controller) ────┘
                       │
              Forward Controller ──┐
                       │           │ bypass paths
                       └───────────┘

Circuit Files​

Tech Stack​

Overview​

Clarity PMA (Project Manager Assistant) is an AI-powered tool that turns messy meeting notes, video call transcripts, and brain-dump text files into structured, actionable work items — all running locally on your machine with zero data leaving your device.

It uses Ollama to run a large language model (default: Llama 3) directly on your hardware. A carefully crafted system prompt instructs the model to extract tasks, bugs, chores, and documentation items from unstructured text, outputting them as validated JSON. The parsed work items are saved locally and optionally pushed to your project management platform of choice — Plane.so, Azure DevOps, GitHub Projects, or just stdout.

Key Features​

• Transcript-to-task conversion: Feed any .txt or .vtt transcript and receive structured work items with titles, descriptions, acceptance criteria, task breakdowns, types, and components
• Local-first privacy: All LLM inference runs via Ollama on your own hardware — no API keys, no cloud dependency, no data exfiltration
• Structured JSON output: Ollama-native JSON mode with Pydantic schema enforcement ensures consistently valid, well-typed outputs every time
• Pydantic validation: WorkItem model validates title length, type enumeration, and required fields before any work item is created
• Multi-platform posting: Push work items to Plane.so (REST API), Azure DevOps (SDK), GitHub Projects (ProjectsV2 API), or console output
• Three prompt variants: Basic (simple extraction), Agile (user story format), and Engineering (technical task breakdown) — selectable via config
• Docker Compose for Ollama: GPU-enabled NVIDIA Docker setup to run the LLM server in a container
• Deterministic output: Temperature set to 0 in Ollama for reproducible, consistent results across runs

Architecture​

main.py
  └── WorkflowManager (orchestrator)
        ├── IAgent (interface)
        │     └── OllamaAgent ─── connects to local Ollama server (JSON mode, temp=0)
        ├── IClient (interface)
        │     ├── PlaneClient    ─── Plane.so REST API
        │     ├── AzureClient    ─── Azure DevOps SDK
        │     ├── GithubClient   ─── GitHub Issues + ProjectsV2 API
        │     └── ConsoleClient  ─── stdout (debug/testing)
        ├── SystemPrompt         ─── 3 variants (A: basic, B: agile, C: engineering)
        ├── WorkflowManagerParser ─── JSON → Pydantic WorkItem validation
        ├── Storage              ─── Read transcripts, save work items to disk
        ├── Config               ─── .env loader (Ollama host, model, platform tokens)
        └── Log                  ─── Custom logger (INFO + SUCCESS levels)

WorkItem Data Model​

Tech Stack​

Overview​

Busa Woodward is a Dubai-based "Experience Engineering" firm that shapes cultural narratives and public experiences — from mega-events and cultural districts to urban developments and destination-building projects. Their corporate website is a fully CMS-driven Next.js application that presents the firm's studio, projects, labs, people, story, and insights through a rich visual experience.

Every page, every hero carousel, every testimonial, and every FAQ section is composed from block-based content managed in Directus — no content is hardcoded. When editors update content in the CMS, webhooks trigger Next.js ISR revalidation so changes go live immediately without a redeploy.

Key Features​

• Fully CMS-driven: All pages are dynamic block compositions from Directus — editors have complete control without touching code
• WordPress migration: Extensive redirect map handles legacy WordPress URLs seamlessly
• Complex hero carousel: Multi-category navigation with animated sidebar tabs and Embla smooth scrolling
• Rich typography: 58 custom OTF font files self-hosted for branded visual identity
• GitOps deployment: GitHub Actions builds the Docker image, updates the GitOps repository, and ArgoCD syncs to Kubernetes
• SEO: Dynamic sitemap, per-page metadata from CMS, OpenGraph images

Architecture​

Busa Woodward follows the headless CMS pattern — a single Next.js frontend talking directly to Directus via its SDK:

No separate API backend — the frontend fetches everything from Directus SDK calls. Three minimal Next.js API routes handle the contact form (AWS SES), ISR revalidation webhooks, and cache busting.

Frontend — Next.js App Router​

The frontend is built with Next.js App Router and styled with Tailwind CSS, featuring a custom purple theme. It ships with 58 self-hosted OTF font files across the Aktiv Grotesk and Gestura families.

Key Pages​

• Home — Hero carousel with sidebar tabs, language-section typewriter effect, project highlights
• Studio — Firm philosophy and approach
• Projects — Case study gallery with filtering
• Labs — Innovation and experimental work
• Story — Brand narrative and history
• People — Team profiles and leadership
• Insights — Articles, thought leadership, and blog content
• Expos — Exhibition showcase
• Gallery — Visual portfolio
• Contact — Contact form with AWS SES email delivery

Notable Components​

• HeroCarousel — Multi-category Embla carousel with color-coded sidebar tab navigation and autoplay
• HomeLanguageSection — Typewriter text animation for taglines
• FAQ accordion — Expandable Q&A sections
• Testimonials slider — Client testimonial carousel

CMS — Directus Headless Backend​

Directus manages 28 collections including pages, projects, articles, team members, headers, footers, global settings, and reusable content blocks (hero sections, sliders, FAQs, testimonials, SEO metadata).

Content flows to the frontend through Directus SDK calls. When editors publish changes, Directus fires a webhook to /api/revalidate, triggering Next.js Incremental Static Regeneration — the site rebuilds affected pages without a full deployment.

Static assets (images, documents) are stored in a Hetzner S3 bucket and served through Bunny CDN (cdt-busa-woodward.b-cdn.net) for fast global delivery.

Tech Stack​

Overview​

Booking Clinic is a multi-tenant SaaS platform that lets healthcare clinics and appointment-based businesses manage their entire booking workflow. Each client (tenant) gets their own workspace with customizable branding, services, staff profiles, locations, and scheduling — all managed through a shared admin dashboard. End customers can book appointments through personalized public booking pages, with deep-link URLs that securely embed tenant and provider context.

The platform handles everything from provider schedules (recurring weekly slots) to public booking tokens, appointment confirmations, and email notifications — powered by a dedicated Rust email microservice that dispatches templated messages through AWS SES.

Key Features​

• Multi-tenant isolation: Workspace-scoped entities via BaseWorkspaceEntity, per-tenant branding, settings, and users
• Public booking with deep links: Cryptographically-secure time-limited tokens allow unauthenticated visitors to book appointments
• Advanced scheduling: Recurring weekly slots via daysOfWeek JSON, templates for standardizing provider availability
• Polyglot architecture: Node.js API for business logic, Next.js for the UI, and Rust for high-performance email dispatch — each in the right language for the job
• Fine-grained RBAC: Permissions like booking.serviceOfferingSlot.create validated through OxideAuth on every request
• Generic CRUD framework: 14 entities get full Create-Read-Update-Delete with RBAC through a single BaseModelRouter pattern

Architecture​

Booking Clinic runs as a polyglot multi-service system orchestrated via Docker Compose or Kubernetes:

• www — Next.js administrative dashboard and public booking frontend
• api — Express.js REST API with generic CRUD framework and RBAC
• email — Rust/Axum microservice for event-driven email delivery
• PostgreSQL — primary relational database for bookings and tenant data
• Redis — caching layer and pub/sub event bus for email dispatch

The API proxies all authentication through OxideAuth, CODATIVITY's centralized auth service, using service account JWTs. This keeps identity management separate from business logic.

Service-to-service flow​

Public user  →  www (booking form)  →  api (validates token, creates booking)
                                         │
                                    PostgreSQL (stores booking)
                                         │
                                    Redis pub/sub (emits event)
                                         │
                                    email (Rust) → AWS SES (sends confirmations)

Services​

www — Next.js Dashboard + Public Booking​

The frontend is a Next.js App Router application using MUI for the UI layer and FullCalendar for the scheduling interface. It serves two audiences through route groups:

• (auth) — login, registration, and auth flow pages
• (dashboard)/[tenant] — admin dashboard with Schedule (FullCalendar), Bookings, Services, Providers, Locations, Users, Templates, Settings, Workspaces, and Notifications
• (simple) — public-facing booking pages accessed via secure deep links

Key frontend features include a compile-time typed service registry using a custom useServiceSWR hook that provides type-safe API calls and automatic caching.

api — Express.js REST Backend​

The API is built on Express.js with TypeScript, using MikroORM for database access. It employs a generic BaseModelRouter pattern — 14 entity types (User, Workspace, Provider, ServiceOffering, Booking, etc.) each get automatic CRUD endpoints with RBAC enforcement.

Authentication goes through OxideAuth: the API validates incoming JWTs and enforces fine-grained permissions like booking.serviceOfferingSlot.create on every route. Storage backends are swappable between local, Azure Blob, and Hetzner S3 via configuration.

email — Rust Microservice​

A dedicated email service written in Rust using the Axum framework. It listens on Redis pub/sub channels for events (booking created, cancelled, reminder triggers) and sends formatted emails via AWS SES. Templates use Handlebars/Tera for flexible HTML generation. Has its own PostgreSQL database for email tracking and logs.

Tech Stack​

Overview​

The Craft Safari is a full-featured e-commerce storefront selling Indian handcrafted goods and artisan products — from home decor and textiles to craft tours and art atelier experiences. The store operates in the UAE market with AED pricing and Geidea payment processing.

The architecture is headless WooCommerce — WordPress handles the product catalog, orders, and blog content through its REST API, while Next.js 15 owns all rendering, caching, and the customer experience. A secure proxy layer keeps WooCommerce API credentials on the server, never exposing them to the browser.

Key Features​

• Headless WooCommerce with secure proxy: WC credentials are server-side only — all API calls funnel through an allowlisted proxy route
• Three-layer caching: ISR (10min), server memory (5min), TanStack Query (5s) — tiered for performance and freshness
• Custom post types: Beyond standard WooCommerce — home-banner, home-promotion, craft-tour, event, workshops for rich content experiences
• Bunny CDN media offloading: Custom WordPress plugin rewrites attachment URLs to CDN
• Geidea payment integration: UAE-specific gateway supporting card payments and digital wallets in AED
• 3D model viewer: @google/model-viewer for interactive product visualization
• Bootstrap 5 + SCSS: Extensive custom styling framework — not Tailwind — with page-level SCSS modules
• Yoast SEO integration: WordPress SEO metadata consumed via yoast_head_json for Next.js generateMetadata()
• Dynamic sitemap: Fetches all products, categories, and blogs from WooCommerce at build time
• Cookie consent + analytics: GDPR-compliant cookie banner with Google Analytics and Meta Pixel integration

Architecture​

A single Next.js frontend with an external WooCommerce backend:

No database is managed in this repository — all product, order, and customer data lives in the external WordPress/WooCommerce instance at admin.thecraftsafari.shop.

Frontend — Next.js App Router with Bootstrap 5​

Built with Next.js 15 App Router, Bootstrap 5 + SCSS, and TanStack Query. Notably, this project uses Bootstrap/SCSS instead of Tailwind — with extensive custom styles in public/scss/main.scss and page-local *.module.scss files.

Pages​

• Home — Hero, category grid, featured products, promotional banner, social proof
• Shop — Product listing with filters, sorting, and search (Fuse.js fuzzy search)
• Category — Category-specific product display
• Product Detail — Full product page with PhotoSwipe gallery, 3D model viewer (@google/model-viewer), product attributes, and add-to-cart
• Blog — WooCommerce blog posts
• Travel Diaries — Custom post type for travel content
• About, Contact — Brand story and contact form
• Indian Crafts / Craft Tours / Art Atelier / Events — Custom post type pages
• Checkout — Multi-step checkout with Geidea payment
• Payment — Payment processing page
• My Account — Orders, addresses, wishlist, profile management
• Cart — Shopping cart with quantity management
• 15 modals — Ask Question, Color Compare, Login, Quick Add, Quick View, Share, Search, and more

WooCommerce Secure Proxy​

All WooCommerce API calls flow through a single Next.js API route at /api/wc. A proxy utility determines which endpoints are public (GET products, categories, tags) vs. authorized (orders, customers, coupons) and enforces the appropriate access rules. The WooCommerce consumer key and secret remain server-side only — the browser never sees them.

Guest checkout is supported through carve-outs that allow anonymous order creation.

Three-Layer Caching​

The storefront implements a tiered caching strategy for performance:

1. Next.js ISR — Pages revalidate every 10 minutes; generateStaticParams() pre-builds category and product pages at build time
2. Server memory cache — Products and categories cached for 5 minutes with a setInterval sweeper for invalidation
3. TanStack Query — Client-side cache with 5-second staleTime for instant UI updates

This means category and product pages load instantly from static cache, while data freshness is maintained through multiple cache layers.

Media Delivery — Bunny CDN​

A custom WordPress PHP plugin rewrites all attachment URLs from the WordPress origin to Bunny CDN (cdt-tcs.b-cdn.net). This offloads media delivery to the CDN edge, reducing load on the WordPress server and improving image load times globally.

Tech Stack​

Overview​

Champions Karate is a full-stack web platform for a martial arts academy operating across five locations in Dubai. The site serves two audiences: prospective students browsing the public marketing website, and academy staff managing the business through an internal admin dashboard.

Built as a single Next.js application with a Strapi headless CMS backend, the platform handles everything from class scheduling and blog management to contact form processing and file uploads. The admin dashboard provides a complete business management interface with Redux state management, role-based access control, and a class timing system that accommodates multiple programs, age groups, and locations.

Key Features​

• Class scheduling system: Enum-based scheduling covering multiple class types, age groups, 5 locations, and 7 days — all configurable from the admin dashboard
• Admin dashboard: Full MUI-themed business management interface with Redux state management
• Contact form with reCAPTCHA: Google reCAPTCHA Enterprise verification for spam prevention
• RTL/LTR layout support: Ready for Arabic with stylis-plugin-rtl
• ISR with 10-second revalidation: Static pages rebuild on content changes via Strapi webhooks
• AWS S3 integration: File uploads stored in S3 for scalability

Architecture​

A www + api split pattern with Strapi serving as both CMS and API:

The frontend communicates with Strapi through REST API calls at the /cms prefix. Strapi handles authentication via its built-in users-permissions plugin and provides content types for blog posts, contact forms, pages, class timings, profiles, and site settings.

Frontend — Next.js Pages Router​

The frontend is a single Next.js 14 application using the Pages Router, styled with MUI v5 and enhanced with Framer Motion and AOS animations.

Public Site Pages​

• Home — Hero, program showcase, location finder, calls-to-action
• About — Academy philosophy, instructors, facilities
• Contact — Contact form with Google reCAPTCHA Enterprise verification
• Classes — Program listings (Karate, Kickboxing, Self-Defence, Fitness, Tots, Private)
• Dojo Locations — Five locations with maps
• Holiday Camps — Seasonal program information
• Blog — Articles and updates

Admin Dashboard​

The dashboard is an MUI-themed SPA-within-Next.js, managed through Redux for state. It provides:

• Dashboard overview — Business metrics and activity
• Blog management — CRUD for articles with rich content
• Classes management — Schedule configuration for multiple programs, age groups, locations, and days
• Contact forms — View and respond to inquiries
• Page editor — Update site content without touching code
• Settings — Site-wide configuration

Backend — Strapi CMS​

Strapi manages all content through a REST API at /cms. Custom endpoints like /cms/profiles/me and /cms/profiles/change-password extend the built-in users-permissions system. Lifecycle hooks automatically create user profiles on registration. The strapi-plugin-email-designer plugin provides customizable email templates for automated communications.

Content types include Blog, ContactForm, Page, ClassTiming, Profile, and SiteSetting — giving non-technical staff full control over the website's content.

Tech Stack​

Architecture​

The pipeline lives in references/scripts/ under the repo. It uses a module-loader pattern — lib/index.sh sources every .sh module in sorted order, guarded against double-includes. The entry point (deploy.sh) sources the loader, then calls into whichever modules it needs.

references/scripts/
├── deploy.sh              # Entry point / orchestrator
└── lib/
    ├── index.sh           # Auto-loader (sources all *.sh in lib/)
    ├── helpers.sh         # die(), dry-run, pushd/popd, timestamps
    ├── docker.sh          # Build & push strategy per environment
    ├── kube.sh            # kubectl apply (local or remote via SSH)
    ├── systemd.sh         # SSH + systemd image-bump for bare-metal
    ├── version.sh         # .env / deploy.yaml / .version snapshot
    ├── git.sh             # Git add + commit
    └── help.sh            # Usage text

The loader pattern means you never need to manually source individual modules — adding a new lib/*.sh file automatically makes its functions available.

How the loader works (lib/index.sh)​

_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
while IFS= read -r -d '' mod; do
    case "$(basename "$mod")" in index.sh) continue ;; esac
    . "$mod"
done < <(find "$_LIB_DIR" -maxdepth 1 -type f -name '*.sh' -print0 | sort -z)

It finds its own directory (handles being sourced from anywhere), then globs every .sh file in the same folder — except itself — and sources them in deterministic alphabetical order. A __LIB_INDEX_SH_SOURCED guard variable prevents double-loading if index.sh is sourced twice in the same shell.

Environments & Deployment Paths​

The pipeline supports three environments, each with a different rollout strategy:

Staging uses Kubernetes. Manifests are SCP'd to a remote control node and applied with kubectl apply -k (Kustomize).

Production uses bare-metal VMs. The pipeline SSHs directly into each host, atomically bumps the IMAGE= line in /etc/default/<service>, then runs systemctl daemon-reload + restart.

Each service directory must contain the corresponding Dockerfile.* or the build fails immediately. You define which directories constitute "services" inside build_all_images().

Quick Reference — All Commands​

# Basic usage pattern
./deploy.sh <version> <env> [options]

# Local development cluster
./deploy.sh 1.4.0 local

# Staging (Kubernetes via SSH)
./deploy.sh 1.4.0 staging

# Production (bare-metal via systemd)
./deploy.sh 1.4.0 production

# Dry-run: print what would happen, make no changes
./deploy.sh --dry-run 1.4.0 staging
DRY_RUN=1 ./deploy.sh 1.4.0 local

# Show help
./deploy.sh --help

Positional arguments:

• version — Semver tag used as the Docker image tag (e.g. 1.4.0)
• env — One of local, staging, production

Options:

• -n, --dry-run — Echo commands instead of executing them
• -h, --help, help — Print usage and exit

Environment variable:

• DRY_RUN=1 — Same effect as --dry-run

Deploy to Kubernetes (local / staging)​

Both local and staging follow the same pattern, differing only in whether kubectl runs on the local machine or over SSH.

Flow​

build_all_images  →  push_all_images (staging only)
       │
       ▼
update_envs       →  bumps version in .env files
                    →  bumps image tags in deploy.yaml
                    →  writes .version snapshot
       │
       ▼
exec_kube         →  copies ./kubernetes/* to the target
                    →  kubectl apply -k (Kustomize overlay)

The Kubernetes module (lib/kube.sh)​

exec_kube() {
    local remote_host="$1"
    [ -z "$remote_host" ] && die "Remote host not specified."

    if [ "$remote_host" = "local" ]; then
        maybe rm -rf ~/kubernetes/<project>/*
        maybe cp -r ./kubernetes/* ~/kubernetes/<project>/
        maybe kubectl apply -k ~/kubernetes/<project> --force
    else
        maybe ssh "$remote_host" rm -rf ~/kubernetes/<project>/*
        maybe scp -r -v ./kubernetes/* "$remote_host":~/kubernetes/<project>/
        maybe ssh "$remote_host" 'kubectl apply -k ~/kubernetes/<project> --force'
    fi
}

Key points:

• Uses Kustomize (-k) — the ./kubernetes/ directory should contain a kustomization.yaml
• For local: copies manifests to the target path and applies directly
• For remote: SCPs manifests, then SSHs and applies
• --force flag ensures resource conflicts are resolved
• The target path (~/kubernetes/<project>/) is a project-specific value — change it to match your layout

Example: staging deploy​

./deploy.sh 1.5.0 staging

What happens:

1. Builds each service with Dockerfile.staging
2. Pushes images to your registry
3. Updates version strings in all .env files
4. Updates image tags in kubernetes/deploy.yaml
5. Writes .version metadata file
6. SCPs manifests to the staging control host
7. Runs kubectl apply -k on the staging cluster
8. Git commits everything

Deploy to SSH Hosts (production)​

Production bypasses Kubernetes entirely — it uses SSH + systemd to update bare-metal VMs running services directly.

Flow​

build_all_images  →  push_all_images
       │
       ▼
update_envs       →  bumps .env files (skips kubernetes/deploy.yaml)
       │
       ▼
systemd_update_remote_host   →  SSHs to each production host
                                 →  edits IMAGE= in /etc/default/<service>
                                 →  systemctl daemon-reload
                                 →  systemctl restart <service>
       │
       ▼
git_commit

The systemd module (lib/systemd.sh)​

For each service listed in systemd_update_remote_host() on each production host:

1. SSH into the host with BatchMode=yes (key-based auth)
2. Check /etc/default/<service> exists
3. Backup the env file: sudo cp -a "$env_file" "${env_file}.bak"
4. Find the first IMAGE= line
5. Replace the tag portion (everything after :) with the new version
6. Write the update via sudo tee + atomic mv
7. Systemctl sequence:

   sudo systemctl daemon-reload
   sudo systemctl restart "${svc}.service"
   sudo systemctl --no-pager --full status "${svc}.service"
   

The full update logic runs remotely via a heredoc — no scripts need to be pre-installed on the target host:

maybye ssh "${SSH_OPTS[@]}" "$host" bash -s -- "$svc" "$new_tag" <<'REMOTE'
set -euo pipefail
svc="$1"
new_tag="$2"
# ... bump IMAGE=, daemon-reload, restart ...
REMOTE

SSH options used:

• BatchMode=yes — never prompt for password (fails if key auth isn't set up)
• StrictHostKeyChecking=accept-new — auto-accept first connection, fail on host-key mismatch
• ConnectTimeout=8 — fail fast if unreachable

Customizing hosts and services​

The hostnames and service names are hard-coded near the top of deploy.sh and inside systemd.sh. Adapt these for your own project:

# deploy.sh — remote hosts
STAGING_HOST="your-k8s-control-node"
PRODUCTION_HOST_1="your-vm-1"
PRODUCTION_HOST_2="your-vm-2"

# systemd.sh — service names (must match /etc/default/<name>)
for svc in your-api your-frontend your-worker; do
    _systemd_remote_update_one "$host" "$svc" "$new_tag"
done

Example: production deploy​

./deploy.sh 2.0.0 production

What happens:

1. Builds all images with Dockerfile.prod
2. Pushes to registry
3. Updates .env files (skips kubernetes/deploy.yaml since UPDATE_KUBE=false)
4. Writes .version
5. For each production host:
   • SSHs in, bumps IMAGE= in /etc/default/<service>
   • Restarts the service via systemctl
   • Repeats for every service
6. Git commits

The Dry-Run System​

Every destructive or state-changing operation is wrapped in maybe:

maybe() {
    if is_dry_run; then
        echo "[DRY-RUN] $*"
    else
        "$@"
    fi
}

This means --dry-run gives you a complete trace of every command that would execute — including docker build, docker push, kubectl apply, ssh commands, sed edits, and git commit — without actually touching anything.

./deploy.sh --dry-run 1.4.0 staging
# Output:
# [DRY-RUN] docker build -f Dockerfile.staging . -t <registry>/<image>:1.4.0
# [DRY-RUN] docker push <registry>/<image>:1.4.0
# ...etc...

State Files Written​

.env / .env.* (any depth-2 file matching)​

NEXT_PUBLIC_APP_VERSION=1.4.0

The env-var name (NEXT_PUBLIC_APP_VERSION) is Next.js-specific — change the grep/sed patterns in version.sh to match your framework.

kubernetes/deploy.yaml (local & staging only)​

All image tags :X.Y.Z are replaced with the new version via regex.

.version (repo root — written on every run)​

CURRENT_VERSION=1.4.0
LAST_DEPLOY_ENV=staging
LAST_DEPLOY_AT=2026-08-03T14:03:11+04:00
LAST_DEPLOY_USER=pierre
GIT_BRANCH=main
GIT_COMMIT_SHA=a1b2c3d

This file is sourced on the next run to provide the OLD_VERSION baseline.

Docker Build Strategy​

Each environment maps to a specific Dockerfile:

dockerfile_for_env() {
    case "$1" in
        local)      echo "Dockerfile.local" ;;
        staging)    echo "Dockerfile.staging" ;;
        production) echo "Dockerfile.prod" ;;
        *)          die "Unknown env '$1'" ;;
    esac
}

The expected Dockerfiles per service directory — defined in build_all_images():

Image naming convention (customize user and image names in build_all_images()):

<registry-user>/<project>-api:<version>
<registry-user>/<project>-frontend:<version>
<registry-user>/<project>-worker:<version>

Complete File Reference​

deploy.sh​

#!/bin/bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"

# load lib
# shellcheck disable=SC1091
. "$REPO_ROOT/lib/index.sh"

# --- REMOTE HOSTS (customize per project) ---
STAGING_HOST="your-k8s-control-node"
PRODUCTION_HOST_1="your-vm-1"
PRODUCTION_HOST_2="your-vm-2"

parse_args() {
	DRY_RUN=0

	while [[ $# -gt 0 ]]; do
		case "$1" in
		-n | --dry-run)
			DRY_RUN=1
			shift
			;;
		-h | --help | help)
			print_help
			exit 0
			;;
		-*)
			die "Unknown flag: $1"
			;;
		*)
			break
			;;
		esac
	done

	NEW_VERSION="${1:-}"
	shift || true
	ENV_NAME="${1:-}"
	shift || true

	[ -z "${NEW_VERSION:-}" ] && die "Version tag not specified."
	[ -z "${ENV_NAME:-}" ] && die "Environment not specified."
	case "$ENV_NAME" in local | staging | production) ;; *) die "Invalid env '$ENV_NAME'. Allowed: local|staging|production." ;; esac

	if [ -n "${1:-}" ]; then
		die "Unknown argument: $1"
	fi
}

run() {
	parse_args "$@"

	if [ -f .version ]; then
		. .version
		OLD_VERSION="${CURRENT_VERSION:-0.0.0}"
	else
		OLD_VERSION="0.0.0"
	fi

	echo "Old Version: $OLD_VERSION"
	echo "New Version: $NEW_VERSION"
	echo "Environment: $ENV_NAME"
	echo "DRY_RUN=${DRY_RUN}"

	UPDATE_KUBE="true"
	[ "$ENV_NAME" = "production" ] && UPDATE_KUBE="false"

	update_envs "$OLD_VERSION" "$NEW_VERSION" "$ENV_NAME" "$UPDATE_KUBE"

	if [ "$ENV_NAME" = "local" ]; then
		echo "==> Local build selected"
		build_all_images "$NEW_VERSION" "$ENV_NAME"
		exec_kube "local"
		echo "Local deploy complete."
	fi

	if [ "$ENV_NAME" = "staging" ]; then
		echo "==> Staging build selected"
		build_all_images "$NEW_VERSION" "$ENV_NAME"
		push_all_images "$NEW_VERSION"
		exec_kube "$STAGING_HOST"
		echo "Staging deploy complete."
	fi

	if [ "$ENV_NAME" = "production" ]; then
		echo "==> Prod build selected"
		build_all_images "$NEW_VERSION" "$ENV_NAME"
		push_all_images "$NEW_VERSION"
		systemd_update_remote_host "$PRODUCTION_HOST_1" "$NEW_VERSION"
		systemd_update_remote_host "$PRODUCTION_HOST_2" "$NEW_VERSION"
		echo "Production deploy complete."
	fi

	git_commit "$NEW_VERSION" "$ENV_NAME"
	echo "Deployment complete"
}

run "$@"

lib/index.sh​

#!/usr/bin/env bash
# Loads all *.sh modules in this directory (except itself), once.

if [ -n "${__LIB_INDEX_SH_SOURCED:-}" ]; then
	return 0 2>/dev/null || exit 0
fi
readonly __LIB_INDEX_SH_SOURCED=1

_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"

while IFS= read -r -d '' mod; do
	case "$(basename "$mod")" in
	index.sh) continue ;;
	esac
	# shellcheck source=/dev/null
	. "$mod"
done < <(find "$_LIB_DIR" -maxdepth 1 -type f -name '*.sh' -print0 | sort -z)

lib/helpers.sh​

#!/usr/bin/env bash
: "${TOP_PID:=$$}"

die() {
	local msg="${1:-"Unknown error"}"
	echo "[ERROR] $msg" >&2
	if [ -n "${USAGE:-}" ]; then echo "$USAGE" >&2; fi
	if [ -n "${TOP_PID:-}" ] && kill -0 "$TOP_PID" 2>/dev/null; then
		kill -s TERM "$TOP_PID"
	else
		exit 1
	fi
}

pushd_quiet() {
	local d="$1"
	echo
	echo "Changing working directory to ./$d..."
	pushd "$d" &>/dev/null || die "Failed to enter $d."
}

popd_quiet() {
	popd &>/dev/null || die "Failed to return to previous directory."
}

is_dry_run() {
	case "${DRY_RUN:-0}" in
	1 | true | TRUE | on | ON | yes | YES) return 0 ;;
	*) return 1 ;;
	esac
}

maybe() {
	if is_dry_run; then
		echo "[DRY-RUN] $*"
	else
		"$@"
	fi
}

now_ts() {
	date -Iseconds
}

lib/docker.sh​

#!/usr/bin/env bash

dockerfile_for_env() {
	case "$1" in
	local) echo "Dockerfile.local" ;;
	staging) echo "Dockerfile.staging" ;;
	production) echo "Dockerfile.prod" ;;
	*) die "Unknown env '$1' for Dockerfile mapping (expected: local|staging|production)" ;;
	esac
}

ensure_dockerfile() {
	local df="$1"
	if [ ! -f "$df" ]; then
		echo "[ERROR] Required Dockerfile not found: $df" >&2
		echo "         CWD: $(pwd)" >&2
		echo "         Available Dockerfile* here:" >&2
		ls -1 Dockerfile* 2>/dev/null || true
		die "Missing Dockerfile: $df"
	fi
}

docker_build() {
	local repo="$1" env="$2"
	[ -z "$repo" ] && die "Repo required for docker build"
	[ -z "$env" ] && die "Env required for docker build"
	local df
	df="$(dockerfile_for_env "$env")"
	ensure_dockerfile "$df"
	echo "Building image: $repo using $df"
	maybe docker build -f "$df" . -t "$repo"
}

docker_push() {
	local repo="$1"
	[ -z "$repo" ] && die "Repo required for docker push"
	maybe docker push "$repo"
}

# --- Customize: add/remove service directories and image names ---
build_all_images() {
	local version="$1" env="$2"
	[ -z "$version" ] && die "Version tag not specified."
	[ -z "$env" ] && die "Env tag not specified."
	local user="your-registry-user"

	pushd_quiet "api"
	docker_build "$user/<project>-api:$version" "$env"
	popd_quiet
	pushd_quiet "www"
	docker_build "$user/<project>-frontend:$version" "$env"
	popd_quiet
	pushd_quiet "worker"
	docker_build "$user/<project>-worker:$version" "$env"
	popd_quiet
}

push_all_images() {
	local version="$1"
	[ -z "$version" ] && die "Version tag not specified."
	local user="your-registry-user"
	maybe docker_push "$user/<project>-api:$version"
	maybe docker_push "$user/<project>-frontend:$version"
	maybe docker_push "$user/<project>-worker:$version"
}

lib/kube.sh​

#!/bin/bash

exec_kube() {
	local remote_host="$1"
	[ -z "$remote_host" ] && die "Remote host not specified."

	if [ "$remote_host" = "local" ]; then
		maybe rm -rf ~/kubernetes/<project>/*
		maybe cp -r ./kubernetes/* ~/kubernetes/<project>/
		maybe kubectl apply -k ~/kubernetes/<project> --force
	else
		maybe ssh "$remote_host" rm -rf ~/kubernetes/<project>/*
		maybe scp -r -v ./kubernetes/* "$remote_host":~/kubernetes/<project>/
		maybe ssh "$remote_host" 'kubectl apply -k ~/kubernetes/<project> --force'
	fi
}

lib/systemd.sh​

#!/bin/bash

SSH_OPTS=(-o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=8)

_systemd_remote_update_one() {
	local host="$1" svc="$2" new_tag="$3"
	echo "INFO: running remote service update for ${svc}.service on HOST: ${host}"

	maybe ssh "${SSH_OPTS[@]}" "$host" bash -s -- "$svc" "$new_tag" <<'REMOTE'
set -euo pipefail
svc="$1"
new_tag="$2"
env_file="/etc/default/${svc}"
if [ ! -f "$env_file" ]; then
  echo "WARN: ${env_file} not found, skipping" >&2
  exit 0
fi
echo "INFO: making backup ${env_file}.bak"
sudo cp -a "$env_file" "${env_file}.bak"
line="$(grep -m1 -E '^IMAGE=' "$env_file" || true)"
if [ -z "$line" ]; then
  echo "WARN: No IMAGE= in ${env_file}; skipping"
else
  image="${line#IMAGE=}"
  if [[ "$image" == *:* ]]; then
    repo="${image%:*}"
    new_image="${repo}:${new_tag}"
  else
    new_image="${image}:${new_tag}"
  fi
  if [ "$image" = "$new_image" ]; then
    echo "INFO: ${env_file} already at ${new_image}"
  else
    echo "UPDATE: ${env_file}  IMAGE=$image -> IMAGE=$new_image"
    sudo awk -v newimg="IMAGE=${new_image}" '
      BEGIN { done=0 }
      {
        if (!done && $0 ~ /^IMAGE=/) { print newimg; done=1 }
        else { print }
      }
    ' "$env_file" | sudo tee "${env_file}.tmp" > /dev/null
    sudo mv "${env_file}.tmp" "$env_file"
  fi
fi
sudo systemctl daemon-reload
sudo systemctl restart "${svc}.service"
sudo systemctl --no-pager --full status "${svc}.service" -n 0 || true
echo "INFO: service reloaded ${svc}.service"
REMOTE
}

# --- Customize: list your systemd service names here ---
systemd_update_remote_host() {
	local host="$1" new_tag="$2"
	for svc in <project>-api <project>-frontend <project>-worker; do
		_systemd_remote_update_one "$host" "$svc" "$new_tag"
	done
}