---

🏛️ Unified Ecosystem & Constitutional Directives

---

Why RexOne Web?

A capable backend is only half a product. The browser still has to manage identity, expired sessions, protected navigation, asynchronous failures, payment handoffs, live connections, loading states, localization, and the thousand small interactions that decide whether a system feels dependable.

RexOne Web exists so that work does not have to be improvised or rebuilt from scratch for every product.

The Purpose: Start from One. Not from Zero.

Instead of burning money and compute wasting AI tokens on weak, inconsistent frontend scaffolding or rebuilding foundational authentication, RBAC dialogs, and real-time state machines again and again for every product, RexOne Web provides a sovereign, production-grade starting point.

Discipline-Driven Development (DDD): The Unvarnished Frontend Truth

RexOne Web pioneers Discipline-Driven Development (DDD) for client-side applications. In an era where AI agents can generate hundreds of React components in seconds, the bottleneck is never component generation—it is preventing chaotic state corruption, brittle DOM hacks, and architectural rot.

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

Fearless Frontend Realities Others Hesitate to Reveal:

1. The Frontend AI Vibe-Coding Mess: An unguided AI agent will gladly dump raw fetch() calls inside UI buttons, invent duplicate state atoms, or tangle business logic into JSX. Within 3 prompts, your context window is hopelessly corrupted. Discipline-Driven Development enforces strict boundaries: UI components own presentation, controllers coordinate outcomes, services handle transport, and models define contracts.
2. The "Full-Stack Server Framework" Quagmire: Cramming API routing, database queries, background tasks, and client hydration into a single node runtime produces fragile houses of cards where a minor framework update breaks production auth and SSR rendering. True engineering enforces client-server separation: an API-first backend (Rails 8) and a sovereign client-first web portal (React 19).
3. Zero Deprecation Shims & Zombie Code: Retaining dead code, backwards-compatibility shims, or duplicate props is cowardice. Under Constitutional Law U14, when a contract is superseded, the old code is wiped out completely.
4. 100% Free Sovereignty: Unlike commercial boilerplates that charge $300–$800 for basic auth or lock RBAC behind "pro tiers", RexOne Web is 100% free, Apache 2.0 open-source, and sovereign.

📊 Architectural Comparison: Why RexOne Wins

RexOne Web stops architectural decay before it starts:

• Server Frameworks on the Frontend Suck: Clumsy server-rendered view hacks cannot match the fluid, state-aware responsiveness demanded by modern users. React 19 + TypeScript provides complete type safety, component modularity, and rich interactive control.
• Client-First Responsibility: Routes, contexts, controllers, services, models, modules, and design primitives have strict, distinct responsibilities.
• The Foundation Bends Around the Product: RexOne Web provides the customer-facing application shell and a complete operational Admin Portal (RBAC, users, products, coupons, feedback, client logs) backed by the same versioned API contracts.

Its boundaries are deliberate. UI components own interaction and presentation. Controllers coordinate application outcomes. Services own transport. Models describe contracts. Contexts own cross-cutting browser state. Modules keep product capabilities together. The result is a foundation that can grow without making every feature depend on every other feature.

And no—the interface was not assembled by stacking dependencies until a demo appeared.

Authentication edge cases were traced. Sensitive passcodes were kept out of URLs. Session replacement and expiry were handled centrally. Runtime and React failures were made observable. Translation keys were organized by domain. Real user journeys are verified by automated Playwright E2E suites. The client is built to remain understandable after the first release, not merely attractive before it.

Who RexOne Web is for

RexOne Web is built for React teams, founder-engineers, and agencies creating authenticated browser products on RexOne Core that need both a customer-facing application foundation and a permission-aware operational portal.

It is a particularly good fit when a web product needs several of these concerns to behave consistently:

• Complete identity, confirmation, recovery, Google sign-in, user self-account deletion, and session-expiry flows.
• User and administrator experiences backed by the same IAM contract.
• Stripe checkout, subscriptions, purchases, and entitlement-aware interfaces.
• Queued AI, media, and notification workflows that update through real-time events.
• Centralized localization, browser-local date and time presentation, analytics, and client telemetry.
• Reusable responsive design primitives instead of one-off page implementations.

RexOne Web is not a generic component showcase or an independent mock frontend. It is the reference browser client for the RexOne ecosystem, and its transport and domain contracts are designed to follow RexOne Core.

What you get

• A working product shell: public, authenticated, profile, commerce, AI, and administration experiences share one routing and state architecture.
• A serious admin client: granular IAM controls navigation and actions across operational resource modules.
• Centralized infrastructure: API interception, socket lifecycle, localization, analytics, telemetry, persistence, and timezone handling stay out of individual pages.
• Reusable interface foundations: forms, dialogs, tables, detail layouts, feedback states, and responsive behavior are shared deliberately.
• Real ecosystem integration: the application consumes RexOne Core's versioned JSON contracts and real-time operation lifecycle.

The philosophy

RexOne Web follows the same doctrine as the core it serves:

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

The difficult part of frontend work is rarely rendering one more screen. It is preserving a system that remains coherent when routes multiply, API contracts evolve, providers fail, languages expand, and product-specific experiences begin to pull in different directions.

So the ambition is not to provide the largest component library or the most elaborate state layer.

It is to provide a clear client foundation—strong enough to carry ambitious products, flexible enough to surrender its shape to them, and disciplined enough that the next developer can follow data from interaction to API and back without archaeology.

Feature map

Architecture

RexOne Web keeps browser concerns explicit and domain behavior grouped.

flowchart LR
    User[User] --> UI[Pages & design components]
    UI --> Contexts[Contexts & Jotai state]
    UI --> Controllers[Controllers]
    Controllers --> Services[Domain services]
    Services --> API[Axios API client]
    API --> Core[RexOne Core]

    Core <-->|Action Cable| Socket[Socket services & hooks]
    Socket --> UI

    Browser[Browser/runtime failures] --> Logs[Client log module]
    Logs --> Core

The main boundaries are:

• design/ owns pages, reusable components, and visual primitives.
• modules/ groups domain behavior such as authentication, payments, AI, logging, and administration.
• controllers/ coordinate responses that are shared outside a single domain module.
• services/ own HTTP, sockets, persistence, and other transport concerns.
• contexts/, hooks, and Jotai atoms own shared client state and lifecycle behavior.
• models/ describe API envelopes, resources, pagination, users, and application data.
• constants/ centralizes storage keys, dialog steps, and URL parameters.
• locales/ owns i18n initialization, typed translation keys, and translation helpers.
• routes/ owns browser routing and public/protected access boundaries.
• e2e/ houses Page Objects, fixtures, and Playwright end-to-end specifications.

The UI does not need to know how Axios is configured, and transport code does not decide how a dialog should behave. That separation keeps provider and backend details from spreading through presentation code.

The client in detail

Authentication & security

• Email-based account discovery followed by sign-in or registration.
• Six-digit numeric passcode creation, confirmation, and sign-in flows.
• Email confirmation code entry and resend cooldowns.
• Automatic drop-off recovery: returning unconfirmed users route directly to email confirmation OTP.
• Forgot-password and reset-passcode flows.
• Google OAuth sign-in, including the Core challenge flow for new accounts.
• In-memory handling of credentials; sensitive values are deliberately excluded from URL parameters.
• JWT-backed authenticated requests through the centralized Axios client.
• Central handling for expired or replaced sessions, with a localized sign-in message.
• Protected and public route boundaries.
• Google logout coordination for Google-backed accounts.
• User self-account deletion: Dedicated Danger Zone in Profile/User settings prompting a destructive confirmation dialog with non-recoverable email warnings and configurable support email contact, followed by session eviction.

Authentication delegates identity rules and token authority to RexOne Core while keeping browser behavior, navigation, and feedback cohesive.

Product analytics

• Firebase Analytics uses the Web stream from the shared RexOne GA4 property.
• Route changes emit view_page centrally without query strings, while successful authentication, onboarding, product, purchase, and notification interactions use the shared action_noun event contract.
• Every event includes platform: web; authenticated sessions use only the opaque RexOne user ID and never send email or other personal data to Analytics.
• Firebase client identifiers are configured through the VITE_FIREBASE_* variables in .env.example.

Routing & access

Client and server paths are defined in src/AppRoutes.ts, giving components and services one source of truth.

Public flows include the landing page, Privacy Policy (/privacy), Terms & Conditions (/terms), sign-in, sign-up, email confirmation, forgotten passcodes, and passcode reset. Protected flows include home, profile, payment, AI, and sign-out. Access checks and current-user requests use the versioned Core API.

Authentication is presented as a URL-addressable dialog flow. This allows redirects from email links and session expiry to land on the correct step while keeping passcodes in memory rather than browser history.

IAM & RBAC Administrative Hierarchy

The client enforces a synchronized three-tier administrative hierarchy:

• super_admin: Complete authority across all features; renders all admin sidebar navigation items.
• admin: Full authority over domain operations (feedbacks, payments, ai, assets, logs), strictly excluded from users and iam. The admin sidebar automatically hides User Management and IAM navigation items.
• Partial Admins (*_admin naming convention): Users holding the base user role plus a specific *_admin role (e.g. feedback_admin). Any role with admin in the name is treated as an admin role.
  • Permission Provenance: Permissions granted to admin roles grant access to both client (/v1/*) and admin (/v1/admin/*) endpoints. Permissions in non-admin roles (such as user) only grant access to /v1/*.
  • Sidebar Visibility: The admin sidebar dynamically renders only the navigation items corresponding to the read_<resource> permissions of their assigned *_admin role.

Administration & Operational Consoles

The client provides a permission-governed operational administration portal (src/modules/admin/). Instead of scattered modals or ad-hoc dialogs, administrative workflows are organized into dedicated operational consoles:

• Modular Domain Consoles: Full-page, searchable workflows for Users (with quick confirmation for unconfirmed accounts), Roles & Permissions (IAM), Products & Pricing (with access grants user inspection), Coupons (with discount audits and batch generation), Notifications & Broadcasts, Entitlements (Accesses), Media Asset Control, Version Catalogues, Chat Moderation, and Feedback Telemetry.
• Unified Form & Table Contracts: Reusable entity forms (CREATE and EDIT modes), compact action buttons, deep filterable tables, and dedicated recycle bins for recovering soft-deleted records. Form molecules include specialized controls such as DateTimePicker and NumberInput (with automated leading-zero sanitization).
• Dynamic Client-Side RBAC: Route guards and sidebar navigation adapt dynamically to the authenticated user's permissions, ensuring non-admin users or partial admins only access authorized modules.
• Interactive Analytics: Overview dashboard KPI cards link directly to corresponding operational tables, while revenue charts incorporate coupon redemptions count and period discounts with accurate current-day metrics.

⚡ Quick Start

Prerequisites

• Node.js 22.13.0 or newer
• npm 10 or newer
• Running RexOne Core API (http://localhost:3000)

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

# 1. Local Development (connects to local Core API at http://localhost:3000)
./scripts/dev.sh
# (or via npm:) npm run dev

# 2. Remote UAT Staging (connects to https://uat.api.rexone.me)
./scripts/uat.sh
# (or via npm:) npm run uat

# 3. Remote Production (connects to https://api.rexone.me)
./scripts/prod.sh
# (or via npm:) npm run prod

By default, the client is immediately available at http://localhost:4000.

---

🧪 Quality Toolchain & Automated Testing

RexOne Web enforces high engineering discipline with strict compile-time checks and dual-layer automated testing:

# 1. Run all unit tests (Vitest) - 43 suites, 371 tests
npm test

# 2. Run Playwright End-to-End user journeys (headless)
npm run test:e2e

# 3. Architecture & i18n invariants validation (LAW.md checks)
npm run check:architecture
npm run check:locales

---

📚 Technical Documentation & Subsystem Architecture

To maintain high architectural discipline without cluttering the primary showcase, exhaustive technical specifications, API contracts, and design tokens are organized in docs/:

---

🚀 Production Deployment & Smoke Testing

Execute an optimized production build:

npm run build

Production bundles are emitted to dist/. The output can be deployed via Coolify, static CDN, or containerized via the included Dockerfile with standard SPA fallback routing.

Test Production Container Locally

To test the exact production multi-stage Docker image and Nginx configuration (SPA routing, health checks, gzip) locally on your Mac:

# 1. Full production Docker + Nginx container test on http://localhost:8080:
./scripts/test_prod.sh
# (or via npm:)
npm run test:prod

# 2. Or test on a custom port:
./scripts/test_prod.sh -p 8081

# 3. Lightweight Vite preview without Docker:
./scripts/test_prod.sh --preview

For the complete Coolify deployment guide, see docs/DEPLOYMENT.md.

Other Repos in RexOne Ecosystem

• RexOne Core — Rails API, IAM, payments, jobs, notifications, storage, AI, administration, and observability
• RexOne Mobile — mobile client

🎨 Rebranding

RexOne Web can be rebranded directly via the master rebranding engine in rexone-core or standalone:

# 1. From rexone-core (rebrands all 3 repositories):
cd ../rexone-core && ./scripts/rebrand.sh

# 2. Local variables in .env.*:
VITE_APP_NAME="My New App Name"

[!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 application is built on top of the RexOne Ecosystem (rex-9). When creating derivative products or white-label applications:

• 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 Web 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 ↑