---

🏛️ Unified Ecosystem & Constitutional Directives

---

Why RexOne Core?

Every product eventually meets the same old enemies: accounts, permissions, billing, uploads, jobs, notifications, dashboards, audit trails, failures, and the darkness between “it works” and “we know why it works.” Especially, the ultimate killer of momentum: “it works on my machine.”

RexOne Core exists because this ground should never have to be conquered again for every product.

The Purpose: Start from One. Not from Zero.

Software has never been easier to generate, but more code does not automatically mean better systems. Human developers and AI coding agents can move fast, but speed without disciplined architecture burns money, AI compute, and human energy—wasting thousands of expensive tokens rewriting weak abstractions, fixing hallucinatory debt, or having to rebuild the exact same foundation again and again for every product.

RexOne turns that repeated, expensive grind into a battle-tested, sovereign baseline.

Discipline-Driven Development (DDD): The Unvarnished Truth

RexOne pioneers Discipline-Driven Development (DDD). While legacy paradigms spent decades debating Domain-Driven Design or Test-Driven Development, the AI era created a fundamentally different reality: typing code is free. Generating 10,000 lines of code takes 30 seconds.

90% of modern software projects never survive to master the business domain because their architecture collapses first under an avalanche of hallucinatory abstractions, conflicting shims, and zombie code. Tests cannot save a rotten architecture.

Discipline-Driven Development establishes that architectural discipline, sovereign foundation, and constitutional law are the primary drivers of sustainable engineering.

You bring the idea. AI writes the code. RexOne keeps both of you from destroying the foundation.

The Brutal Realities Others Hesitate to Reveal:

1. The Vibe-Coding Delusion: Prompting an AI to generate code without an immutable constitution isn't velocity; it's compounding debt at 100x speed. Speed without discipline is just accelerating toward a brick wall.
2. The BaaS Trap: Serverless "5-minute backends" lure developers in with toys, then slap them with a $5,000/mo cloud hostage bill when they need relational integrity, background queues, or compliance audits. Real software runs sovereign PostgreSQL, native queues (Solid Queue), and self-hosted S3 (Garage).
3. The Full-Stack Monolith Lie: Stuffing API controllers, database queries, background tasks, and client hydration into a single node runtime creates fragile, unmaintainable monoliths. True engineering enforces client-server separation.
4. Deprecation Cowardice & Zombie Code: Retaining dead code, backwards-compatibility shims, and duplicate parameter aliases is cowardice. Under Constitutional Law U14, if code is replaced, the old code is wiped out completely. No shims. No legacy bloat.
5. 100% Free Sovereignty: Unlike commercial boilerplates charging $300–$800 for basic auth or gating features behind "pro licenses", RexOne is 100% free, Apache 2.0 open-source, and sovereign. You own your code, your data, and your infrastructure.

⏱️ The 9-Month Delusion: How Teams Waste $200,000 Rebuilding the Exact Same Wheel

Every software founder and engineering lead tells themselves the exact same comfortable lie:

“We just need a lightweight MVP. We’ll build our core feature in 4 weeks, and worry about infrastructure later.”

Here is the unvarnished, brutal truth of what actually happens over the subsequent 9 months:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│  THE TRADITIONAL 9-MONTH ROADMAP TO TECH DEBT COLLAPSE                                 │
├────────────────────────────────────────────────────────────────────────────────────────┤
│  Month 1–2:  Auth & Identity Hell                                                      │
│              JWT tokens, refresh cycles, email confirmation codes, password resets,    │
│              and basic RBAC. The "4-week MVP" is already 100% consumed by login screens.│
│                                                                                        │
│  Month 3–4:  Stripe & Billing Agony                                                    │
│              Checkout sessions seem simple until edge cases hit: webhook reconciliation,│
│              subscription cancellations, proration races, coupon discounts, failed    │
│              invoices, and idempotent state transitions. Two months gone.               │
│                                                                                        │
│  Month 5:    Storage, Media & Async Jobs                                               │
│              S3 bucket credentials, presigned upload tickets, image/video variant      │
│              resizing, Redis broker configuration, and bloated hosting bills.          │
│                                                                                        │
│  Month 6–7:  Web Admin & Real-Time Sync                                                │
│              Operations needs an admin portal. Engineers scramble to build CRUD tables,│
│              metrics charts, and WebSocket event channels from scratch.                │
│                                                                                        │
│  Month 8:    Mobile Client Frustration                                                 │
│              Connecting Flutter or React Native exposes 50 mismatched JSON keys,       │
│              missing endpoints, and fragile auth persistence between Web and Mobile.   │
│                                                                                        │
│  Month 9:    The Tech Debt Wall & Refactoring Paralysis                                │
│              Zero automated tests. Spaghetti code. The team is terrified to touch      │
│              a single line because changing one model breaks 4 disparate screens.      │
└────────────────────────────────────────────────────────────────────────────────────────┘

💸 The Harsh Financial Math:

• Small Team (2–3 Engineers): 9 months of payroll = $150,000 – $300,000 burned.
• Solo Founder / Indie Hacker: 9 months of lost market opportunity, cognitive fatigue, and zero customer validation.
• The Tragedy: 85% of that code had NOTHING to do with the proprietary product idea. It was just the generic, universal plumbing required to run any commercial software.

⚡ The RexOne Day-One Reality:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│  STARTING FROM ONE (REXONE SOVEREIGN FOUNDATION)                                      │
├────────────────────────────────────────────────────────────────────────────────────────┤
│  Day 1:   Spin up Docker. Rails 8 + React 19 + Flutter 3 + Garage S3 + Postgres 18.   │
│           Full Auth, 96 IAM permissions, Stripe billing, and WebSockets live.          │
│                                                                                        │
│  Week 1:  Define your proprietary domain entities and customize brand styling.         │
│                                                                                        │
│  Week 2:  Wire your business logic to existing, fully-tested controllers.              │
│                                                                                        │
│  Week 3:  Run 1,690+ passing automated tests. Deploy staging. Ship to production.      │
└────────────────────────────────────────────────────────────────────────────────────────┘
Result: 8 to 11 months of soul-crushing plumbing deleted. You launch in weeks.

📊 Architectural Comparison: Why RexOne Wins

The Reality: The Exponential AI Tech Debt Cycle

Without immutable architectural boundaries:

Agent 1 invents Pattern A
   ↓
Agent 2 arrives on the next prompt, treats Pattern A as "legacy",
and adds a backward-compatibility shim with Pattern B
   ↓
Agent 3 arrives, bypasses both, and hardcodes an inline workaround
   ↓
Deadlines loom; human developers layer more glue code
   ↓
Context windows fill with duplicate abstractions & zombie code
   ↓
Exponential technical debt & token burn before the product even launches

RexOne breaks this cycle decisively:

• Constitutional Law (LAW.md): Law U14 enforces zero loose code, zero backward-compatibility shims, complete wipeout and replacement. If code deviates from the law, the code is wrong—fix the code. Law U15 enforces human-readable plain English with zero esoteric syntax.
• Operational Agent Governance (AGENTS.md): Strict guidelines for AI coding tools—never read .env secrets, never run destructive git operations, and synchronize documentation in the exact same turn as code changes.
• AI Turns from an Architect into a Worker: The architecture has already been decided. AI works cleanly inside it.

Born from Battle-Tested Production Reality

RexOne was not born from framework fandom or an abstract weekend thought experiment. It is the hard-won distillation of years of shipping real-world production systems across:

• Firebase & Google Ecosystem: Battle-tested as a founding engineer at js.eco (a 3-person team: CEO, CTO, and Htet Naing, scaling rapidly in the US EV charging market). While one of the most systematic, high-growth Google-centric architectures, it proved that proprietary ecosystem lock-in and scattered functions still create immense friction.
• Multi-Cloud & Polyglot Background: Extensive real-world production engineering across AWS SAM, Microsoft Azure, FastAPI (Python), Laravel & TALL/Filament (PHP), NestJS & Next.js (Node/TypeScript), Go, Prisma, MongoDB, MySQL, and PostgreSQL.

The Golden Architectural Rule: Server frameworks on the frontend create clumsy UX; client languages on the backend create loose, messy architectures. RexOne combines the strongest technologies that survived this crucible—Rails 8 API Core + React 19 Web + Flutter 3 Mobile—with crystal-clear boundaries, workload-separated queues, self-hosted S3 storage (Garage), full-stack observability, and constitutional laws.

The foundation is designed to bend around the product, never to make the product kneel before the framework.

Instead of hardcoding a rigid SaaS "Teams" hierarchy into domains where it doesn't belong (which is painful to dismantle if the product is an educational platform, clinic, or marketplace), RexOne provides rock-solid IAM primitives (roles, permissions, and 23 canonical resources), leaving domain hierarchy entirely to the business.

RexOne Core brings startup speed with battle-tested discipline—and zero final-hour whispers of “we should probably build that before launch.”

It is a particularly good fit when you want to:

• Stop writing boilerplate infrastructure and start shipping domain features on day one.
• Keep AI generation on rails: prevent autonomous LLM coders from inventing haphazard abstractions, sprawling directories, or unmaintainable architectural debt.
• Have complete confidence in reviews: clean boundaries mean reviewing code is effortless with zero garbage to wade through.
• Rely on automated tests: end-to-end verification across both the backend server and client applications.
• Operate a unified ecosystem:
  • Authentication and explicit role-based access control.
  • Stripe payments connected to durable entitlements.
  • Provider-neutral media storage and background optimization.
  • In-app, push, email, and real-time notification delivery.
  • Queued AI and speech workflows that survive client disconnection.
  • Operational dashboards, client telemetry, audit trails, and health checks.
  • Reference React and Flutter clients consuming the exact same contracts.

RexOne is not a no-code application generator or a promise that every product domain is already modeled. It supplies the disciplined platform foundation; the product remains responsible for its own domain, workflows, interface, and operating decisions.

What you get

• One coherent system: identity, authorization, commerce, media, async work, notifications, and observability are designed to cooperate.
• Real client contracts: RexOne Web and RexOne Mobile exercise the same versioned API and real-time events.
• Replaceable providers: external services remain behind focused client and base contracts.
• Inspectable operations: queues, cache, sockets, performance, backend errors, and frontend telemetry have explicit operational surfaces.
• A documented engineering standard: architectural constraints, API conventions, lifecycle rules, and cross-client responsibilities are written down and tested.

The public open-source growth roadmap tracks how RexOne will improve evaluation, evidence, contribution readiness, and responsible distribution.

The philosophy

RexOne Core follows a simple doctrine:

Clarity before cleverness. Precision before haste. Simplicity without weakness. Strength without spectacle.

Years of building software teach the same lesson as any long campaign: the first victory is easy to celebrate; surviving everything that follows is the true test.

The difficult part is rarely another controller or CRUD endpoint. It is preserving a system that remains understandable when the product grows, integrations multiply, failures arrive from unfamiliar directions, and the original developer is no longer the only one carrying the blade.

So the ambition was never to build the largest foundation possible.

It was to build a clear one—strong enough to carry ambitious products, flexible enough to surrender its shape to them, and disciplined enough that the next developer can enter the codebase without a map drawn in blood.

No prophecy. No magic. No shortcuts disguised as momentum.

Just deliberate engineering, tested boundaries, and a foundation built to remain standing.

Feature map

Architecture

RexOne Core keeps framework concerns conventional and integrations replaceable.

Controllers own HTTP contracts, models own data rules, services own business and provider boundaries, jobs own deferred work, and serializers own response representation. Serializers standardize on 5 canonical methods (record, collection, collection_pagy, record_attributes, collection_attributes), ensuring uniform JSON:API representations and eliminating raw serialization logic from controllers. All collection endpoints enforce Pagy offset pagination (Law U8), returning standard pagination envelopes and defaulting to a complete single page when parameters are omitted.

flowchart LR
    Clients[Web & mobile clients] --> API[Rails API]
    Clients <-->|Action Cable| Realtime[Solid Cable]

    API --> Auth[Authentication & IAM]
    API --> Domain[Product domain]
    API --> Services[Service interfaces]
    API --> Jobs[Solid Queue]

    Domain --> PostgreSQL[(PostgreSQL)]
    Auth --> PostgreSQL
    Jobs --> PostgreSQL

    Services --> Stripe[Stripe]
    Services --> OneSignal[Push]
    Services --> Brevo[Email]
    Services --> Storage[Garage S3 · Cloudinary]
    Services --> AI[DeepSeek · Google Gemini]
    Services --> Speech[Nova · Azure Speech]

    Jobs --> Services
    Jobs --> MediaWorker[Media Worker · libvips/FFmpeg]
    API --> Observability[Pulse · RED · client logs]

External vendor and provider integrations live behind focused gateway clients (e.g., payment, storage, AI, speech, and notification clients). Swapping or extending an upstream vendor never leaks into controllers or domain logic.

For example, queued AI chat orchestrates message chunking, multi-provider execution (DeepSeek, Google Gemini), universal bidirectional TOON serialization (30-60% token savings, LLMs never eat or output raw JSON), and live WebSocket streaming through clean service boundaries with server-owned profiles and run telemetry. For deep implementation details, see the AI Manual and Foundation Guide.

The same principle applies to product-specific functionality: the foundation provides the structure, while the product remains free to define its own domain, workflows, and experience.

Background processing & Concurrency Architecture

Solid Queue is part of the application architecture, not an afterthought. RexOne leverages a hybrid Fiber + Thread concurrency model powered by Ruby Fibers (async), Rails 8 fiber isolation (config.active_support.isolation_level = :fiber), and Solid Queue 1.7.0:

Dynamic Workload Elasticity Under All Conditions

1. Uneven Workload Spikes (e.g. zero AI traffic, surge in notifications): All I/O queues ([ payments, ai, notifications, default ]) are pooled under the fiber worker with deterministic priority order. When notifications surge, all 50 fibers instantly pivot to deliver notifications. When AI requests spike, free fibers immediately prioritize AI completions. Zero idle worker capacity is wasted.
2. Low Workload / Idle State: Fibers run on a single cooperative event reactor. When queues are empty, context switching drops to zero, CPU usage is near-zero, and Active Record releases idle database connections back to PostgreSQL.
3. Full System Saturation: Up to 50 concurrent I/O operations execute simultaneously within a single worker process without OS thread thrashing, using only 5–10 active database connections. CPU-bound media operations remain isolated in the media container so image/video compression never starves payment webhooks or live chat completions.
4. Exact Development & Production Parity: config/queue.yml maintains the exact same fiber + thread configuration in both development and production, allowing engineers to observe and benchmark real-world concurrent execution locally.

The API, worker (waka), and media processor run as separate services in Docker, keeping request handling, async I/O, and CPU-intensive operations independently scalable.

⚡ Quick Start

With Docker installed, you do not need multiple terminals. All Core services (PostgreSQL 18, Rails 8 API, Solid Queue workers, self-hosted Garage S3 storage, and media processor) run together in a single command:

git clone https://github.com/rex-9/rexone-core.git
cd rexone-core && git switch dev
cp .env.example .env
./scripts/install_pre_commit.sh
./scripts/dev.sh

Seed the initial IAM roles, accounts, and client version (1.0.0):

docker compose -f docker-compose.dev.yaml exec api bin/rails db:seed

Start the companion RexOne Web client:

cd ../rexone-web && ./scripts/dev.sh

[!TIP] Testing Stripe payments locally? Forward webhooks in an optional second terminal: ./scripts/listen_webhook.sh. For granular debugging commands and manual process supervision, see the Ecosystem Quick Start.

---

🎛️ Operations & Glass-Box Observability

Built-in operational consoles are mounted directly into the engine, secured by administrative RBAC:

• Resource Administration: /admin (Administrate engine for core models, users, and credentials)
• AI Profiles & Diagnostics: /admin/ai/profiles (prompt models) & /admin/ai/runs (telemetry audit)
• Application Performance Monitoring (APM): /admin/pulse (request, SQL query, and job latency metrics)
• Error Tracking: /admin/red (Rails Error Dashboard with stack traces and request parameters)
• Queue & Real-Time Inspection: /admin/queue (Solid Queue), /admin/cache, and /admin/cable
• Interactive API Documentation: /api-docs (Swagger / OpenAPI 3.0 specification)
• System Health: /up (automated zero-downtime container health probes)

Client runtime errors are accepted at POST /v1/client/logs and correlated with backend traces.

---

📚 Technical Documentation & Subsystem Architecture

To maintain high architectural discipline without cluttering the primary showcase, exhaustive technical specifications, API routes, and operational playbooks are organized in docs/:

---

🚀 Production Deployment & Security

The production image is multi-stage, runs as an unprivileged non-root user, precompiles Bootsnap, and includes health-check probes.

• Zero-Trust Boot Guard: Refuses to boot if production keys (RAILS_SECRET_KEY_BASE, PG_PASSWORD, S3_ADMIN_TOKEN) match placeholders.
• Automated VPS Maintenance: Includes ./scripts/vps_cleanup.sh for recurring Coolify image pruning and builder cache recycling.

For the complete production deployment playbook, see docs/DEPLOYMENT.md.

🧹 Automated Telemetry & Log Retention (At a Glance)

All logs and database monitoring tables are governed by automated retention policies to guarantee zero disk exhaustion. Complete maintenance guide: docs/MAINTENANCE.md.

🎨 Rebranding

RexOne Core serves as the master rebranding engine for the entire ecosystem:

# 1. Rebrand all 3 repositories from rexone-core:
./scripts/rebrand.sh brand.config.json

# 2. Local environment variables in .env:
APP_NAME="My New App Name"
DEFAULT_MAIL_SENDER="no-reply@mynewapp.com"
FROM_EMAIL="support@mynewapp.com"

[!NOTE] The rebranding script intentionally leaves the landing module (src/modules/landing) and SEO / AI discovery assets (index.html metadata/Schema.org, robots.txt, sitemap.xml, llms.txt, llms-full.txt) completely untouched. RexOne SEO belongs to the foundation architecture; product-specific landing and SEO design are 100% the developer's responsibility.

---

🏛️ Ecosystem Lineage & Attribution

This API core is built on top of the RexOne Ecosystem (rex-9). When creating derivative products or white-label backends:

• Developers and creators are warmly encouraged to preserve ecosystem credit in documentation to support the project.
• All development must strictly adhere to the constitutional engineering standards in LAW.md and ECOSYSTEM.md.

---

💖 Sponsor & Support RexOne

"I'm not a wealthy founder or a venture-backed company ~ I'm an independent developer and meditator who built RexOne with my own hands. I could have easily closed-sourced this enterprise foundation or charged $800+ behind a commercial paywall. Instead, out of pure loving-kindness (mettā) cultivated through my meditation journey under Theravada Buddhist teachings, I chose to gift RexOne 100% free and open-source under Apache 2.0 to empower builders, indie hackers, and learners worldwide.

If this foundation saves you months of engineering, thousands of dollars, or sparks your product journey, please consider supporting me so I can sustain my life and craft. Kindly return the loving-kindness: Sponsor Rex on GitHub and star the repositories. Thank you so much for your generosity and kindness. 🙏"

RexOne is architected, forged, and maintained by Rex (@rex-9). If RexOne saves you engineering months, AI tokens, or cloud compute costs, please consider supporting the foundation!

👉 Sponsor Rex on GitHub

---

🕯️ The Candle Philosophy of Open Source

"Sharing is like lighting candles from one candle to another: sharing one's light does not make its own flame dimmer or weaker, but the world illuminates more and more with each light shared... making the world more and more beautiful... one light at a time..."

— Htet Naing (Rex9), Creator of RexOne

Author

Architected with Discipline-Driven Development (DDD), by Htet Naing (Rex9).

A full-stack architect, product craftsman, and long-time practitioner of meditation.

I build systems the same way I approach the path itself: with a clear mind, deliberate steps, and zero unnecessary weight.

• Creator: Htet Naing (@rex-9)
• Portfolio: rex9.me
• LinkedIn: Htet Naing (rex9)
• X / Twitter: @htetnaing0814

Built with ❤️ by Htet Naing (Rex9) on the RexOne Ecosystem

Back to top ↑