Engineering Onnyth: Architecture & Systems Design
An exhaustive architectural review of Onnyth's full-stack implementation: from hexagonal domain boundaries in Java 21 to React Native's New Architecture.
End-to-End System Design
A decoupled client-server architecture balancing rapid mobile iteration with enterprise backend reliability and strong data integrity.
Current Deployment Topology
Live infrastructure verified in production and continuous integration.
- • TypeScript Feature Modules
- • Zustand State Stores
- • Expo Router (Typed Navigation)
- • JWT Bearer Interceptors
- • 16 REST Controllers
- • Spring Security OAuth2 (JWT)
- • Spring Data JPA & Hibernate
- • 24 Flyway Migrations
- • OpenAPI 3.0 / Swagger UI
- • PostgreSQL Relational DB
- • Supabase Auth (JWT Issuance)
- • Supabase S3 Object Storage
- • User Graphs & Scores
- • Docker Temurin 21 Container
- • Railway Managed Hosting
- • Spring Actuator Health Probes
- • GitHub Actions Workflows
Stateless Cryptographic Security
Supabase serves as the identity provider, generating asymmetric RS256 JWT tokens. Spring Security functions as an autonomous OAuth2 Resource Server, verifying token signatures locally using public keys without requiring continuous auth database lookups.
Zero-Drift Database Migrations
With 24 versioned Flyway SQL migrations, the database schema evolves deterministically. No automated JPA schema auto-generation runs in production. Test suites leverage Testcontainers to execute these exact migration files on real disposable PostgreSQL engines.
Feature-Driven Modularity
Both the Spring Boot and React Native codebases are organized around feature domains: Auth, Profile, Activities, Friends, Leaderboards, Quests, and Cosmetics. This prevents spaghetti code and ensures independent domain refactoring.
Hermetic Test Infrastructure
36+ test files utilize Testcontainers (real Postgres via Docker), WireMock (mocking Supabase API), and PITest mutation testing. Code coverage is backed by fault-injection verification to ensure tests assert true business logic.
Java 21, Spring Boot 3.5 & Hexagonal Architecture
The backend service is structured following Hexagonal Architecture (Ports & Adapters). Core domain models, aggregates, and business rules remain strictly decoupled from infrastructure frameworks, persistence adapters, and web controllers.
Domain Core
Pure Java business logic for scoring algorithms, rank tier thresholds, cooldown enforcement, and achievement qualification.
Inbound Ports & Web
16 REST controllers exposing strictly typed DTO contracts documented via OpenAPI 3.0 / Swagger UI.
Outbound Adapters
Spring Data JPA repositories, Supabase storage clients, and event publication adapters.
Key modules migrated to hexagonal architecture include: Registration, Feed, Quest, Achievement, Store/Cosmetics, and Shared Kernel. This prevents domain bleed and allows switching underlying infrastructure without impacting business rules.
Stateless JWT Flow with Supabase & Spring Security
Authentication uses a dual-tier identity separation architecture:
Client (Expo) ──[Credentials]──> Supabase Auth (Issues RS256 JWT)
Client (Expo) ──[Bearer JWT]────> Spring Boot (Validates JWT locally via JWKS)
Spring Security ────────────────> Sets SecurityContext (Stateless, 0 DB Auth Queries)- ✓Stateless Resource Server: The Spring Boot API does not store sessions in memory. It verifies incoming tokens using Supabase's public cryptographic keys via RFC 7519 JSON Web Key Sets (JWKS).
- ✓Fine-Grained Authority Filters: Endpoints are locked by default; public paths (health checks, OpenAPI docs) are explicitly whitelisted.
- ✓Client Token Interceptors: The React Native mobile client transparently handles token caching, Authorization header injection, and refresh cycling.
PostgreSQL Schema Evolution & 24 Flyway Migrations
Rather than relying on Hibernate's dangerous ddl-auto: update, all database evolution is managed through Flyway.
24 Versioned SQL Migrations
Explicit DDL tracking every schema transformation: users, profiles, friendships, categories, activities, cooldowns, achievements, cosmetics, and indexes.
ACID Transactional Guarantees
Coin deductions and cosmetic item unlocks are wrapped in strict DB transactions with row-level integrity checks to eliminate race conditions.
BookmarkCreated) have been introduced in the backend, but the primary transactional layer relies on optimized PostgreSQL queries and indexing.Expo, React Native 0.79 & New Architecture
The mobile application is built with Expo SDK 52 and React Native 0.79 with the New Architecture (Fabric renderer + TurboModules) enabled for ultra-smooth 60fps animations and instant gesture responsiveness.
Atomic Zustand Stores
Individual, lightweight stores per feature (auth, profile, friends, leaderboards, activities, store) avoiding monolithic context re-renders.
Typed Expo Router
File-based routing with strict route parameter types, tab navigation stacks, and modal sheet presenters.
194 Passing Tests
100% test pass rate across Jest and React Native Testing Library covering state transitions, API handlers, and UI components.
Hermetic Integration & Mutation Testing
Testcontainers
Integration tests launch real PostgreSQL Docker containers dynamically. Tests run real SQL migrations and JPA queries, preventing in-memory H2 dialect discrepancies.
WireMock
External HTTP boundaries (Supabase token validation, avatar upload endpoints) are hermetically mocked, allowing tests to run reliably in offline CI runners.
PITest Mutation Testing
Beyond simple line coverage, PITest introduces synthetic bytecode mutations (inverting conditionals, altering return values) to guarantee assertions actually catch bugs.
Interested in the Consumer Experience?
View the public-facing product landing page and interactive mobile app screens.