Ship enterprise-grade, multi-modal AI products — Chat · Image · Video · Speech · RAG · PromptOps · Tool Calling · MCP — entirely on your own infrastructure.
Most AI frameworks force a choice: cloud convenience or data sovereignty. Orasaka eliminates that trade-off.
Built on Java 21 Virtual Threads, Spring AI 1.1, and a strict Hexagonal Architecture enforced at compile time by ArchUnit, Orasaka delivers a production-grade AI orchestration engine that runs entirely on-premise — Apple Silicon, CUDA, or bare metal — with zero cloud dependencies.
For Founders: A single
npx orasaka devcommand spins up your entire sovereign AI stack — Java Gateway, dual Next.js web apps, and a 6-screen mobile client — in parallel. Ship faster than your competitors can provision cloud credits.For Engineers: A clean hexagonal boundary with 15 pipeline interceptors, compile-time governance guards, and a
SovereignWorkflowContextdomain contract that makes extending the engine feel like writing a plugin, not fighting a framework.For Enterprise: Loi 25 / GDPR-compliant by architecture, not by configuration. Every LLM call, every vector query, every model inference stays on your network. ArchUnit tests enforce it. SonarCloud validates it. Testcontainers prove it.
| Cinematic Video Pipeline | High-Fidelity Image Generation |
|---|---|
AnimateDiff-Lightning (MPS)video_output_20260601_204836.mp4 |
Stable Diffusion 1.5 (MPS) |
🔐 Cinematic Login — Frosted Glass Auth with OAuth2 & Credential Flow
Secure entry point with GitHub / Google SSO, glassmorphism design, and animated feedback.
🚀 One Command to Rule Them All — Full Stack Dev Launch
npx orasaka dev spins up Gateway, Web Client, Admin Console & AI engines in parallel.
🧠 Local AI, Zero Cloud — Streaming Chat Powered by Ollama
Real-time SSE streaming with on-device LLMs. Your data never leaves your machine.
Prompt Transparency (reproducibility configurations)
- Video config — Cinematic cyberpunk sequence parameters
- Image config — Photorealistic cityscape generation settings
Three commands to sovereign AI:
# 1. Interactive setup — detects hardware, configures topology, generates .env
npx orasaka install
# 2. Launch infrastructure (Postgres, Redis, RabbitMQ, Ollama, LocalAI)
npx orasaka start
# 3. Spin up the entire development stack in parallel
npx orasaka devWhat
orasaka devlaunches simultaneously:
Prefix Service Port COREJava Spring Boot Gateway 8080 WEB-CLIENTNext.js 16 Client App 3000 WEB-ADMINSecOps Admin Console 3001 MOBILEExpo SDK 53 Mobile App 8081 All processes stream color-coded output with aligned prefixes.
Ctrl+Cgracefully shuts everything down.
Selective launch — need the Gateway running in IntelliJ for debugging?
npx orasaka dev --skip-core # Launch everything except the Gateway
npx orasaka dev --skip-mobile # Skip the Expo dev servernpm script shortcuts (from orasaka-cli/):
npm run check # Verify tools are installed (non-destructive)
npm run status # Check which services are running (UP/DOWN)
npm run setup # Full wizard: tools + topology + .env generation
npm run start:dev # Launch WEB-CLIENT + WEB-ADMIN (skip core & mobile)Orasaka enforces a strict separation between what the system must achieve and how it executes:
| Layer | Responsibility | Owns | Location |
|---|---|---|---|
| Business | Declares intent, policies, and domain rules | SovereignWorkflowContext, .md persona templates, interceptor policy sets |
orasaka-framework/orasaka-business/ |
| Core | Executes mechanics without opinion | DynamicPipelineExecutor, .st engine templates, PromptContext state machine |
orasaka-framework/orasaka-core/ |
| Gateway | Translates between hexagons | SovereignWorkflowAdapter — sole adapter mapping business context to core types |
orasaka-apps/orasaka-gateway/ |
The contract is absolute. Business code never imports Core infrastructure types. Core code never contains business logic. The Gateway is the only translation boundary between hexagons. ArchUnit's
GovernanceTestenforces this at compile time — violations fail the build.
The Business layer declares "What" via a self-validating SovereignWorkflowContext record. The Gateway's SovereignWorkflowAdapter translates this into Core infrastructure types, mapping fields into namespaced Context.preferences:
| Namespace | Purpose |
|---|---|
orasaka.pipeline.* |
Pipeline directives (contextId, forced/skipped interceptors) |
orasaka.user.* |
User-level attributes (tier, RBAC) |
orasaka.user.meta.* |
Flattened business metadata |
Fifteen pipeline filters orchestrate every AI request — loaded via Spring AutoConfiguration, ordered by priority, and independently testable:
| Order | Interceptor | Submodule | AI-Dep | Purpose |
|---|---|---|---|---|
| 1 | UserContextResolver |
interceptor-context |
— | Load user profile, RBAC tier |
| 2 | SystemContextInjector |
interceptor-context |
— | Environment signals, active tools, system metadata |
| 3 | LanguageAlignmentInterceptor |
interceptor-translation |
— | Force LLM reasoning in English |
| 5 | MemoryInterceptor |
interceptor-enrichment |
— | FIFO conversation history prepend |
| — | RagInterceptor |
interceptor-enrichment |
— | Tenant-isolated vector store RAG context |
| — | McpInterceptor |
interceptor-enrichment |
— | Resolve external MCP server tools and data |
| 6 | RefinerInterceptor |
interceptor-reformulation |
✓ | Refine user query into precise instruction |
| 7 | RouterInterceptor |
interceptor-reformulation |
✓ | Classify intent and route to optimal model |
| — | ToolInterceptor |
interceptor-tooling |
— | Dynamic tool registration and callbacks |
| 9 | CostShieldInterceptor |
interceptor-validation |
— | Auto-shift to cloud if local memory > 85% |
| ∞ | QuantumValidationAdvisor |
interceptor-validation |
✓ | 4-tier closed-loop validation |
graph TD
WebClient["orasaka-web-client (Next.js :3000)"] -->|BFF Proxy| GW["orasaka-gateway (:8080)"]
Admin["orasaka-web-admin (:3001)"] -->|BFF Proxy| GW
Mobile["orasaka-mobile-client (Expo)"] -->|BFF Proxy| GW
CLI["orasaka-cli"] -->|SSE Tunnel| GW
GW --> Core["orasaka-core (Stateless Engine)"]
GW --> ID["orasaka-identity (Security & RBAC)"]
GW --> Tools["orasaka-tools (MCP & APIs)"]
Core --> PersistApp["orasaka-persistence/app"]
ID --> PersistId["orasaka-persistence/identity"]
Tools -->|Implements Ports| Core
Interceptors["orasaka-interceptors"] -->|AutoConfig SPI| Core
subgraph InterceptorModules ["Interceptor Submodules"]
direction LR
Ctx["context"] ~~~ Enr["enrichment"] ~~~ Trans["translation"]
Reform["reformulation"] ~~~ Tooling["tooling"] ~~~ Valid["validation"]
end
Interceptors --- InterceptorModules
Business["orasaka-business (Prompt Templates)"] -.->|ResourceLoader| Core
GW -.->|AMQP| RMQ["RabbitMQ (:5672)"]
RMQ -.->|Async Jobs| WorkerJava["orasaka-workers/external-services (:8082)"]
RMQ -.->|Video Tasks| WorkerPython["orasaka-workers/video (:8188)"]
DB[("PostgreSQL / Redis")]
PersistApp --> DB
PersistId --> DB
WorkerJava --> DB
orasaka/
├── orasaka-framework/ # Shared libraries — no runnable applications
│ ├── orasaka-core/ # Stateless AI orchestration engine
│ │ └── src/main/resources/prompts/ # Engine-level .st templates (allow-listed)
│ ├── orasaka-identity/ # Pure Java user domain, RBAC, password hashing
│ ├── orasaka-business/ # Business prompt templates & domain context
│ │ └── src/main/resources/prompts/ # Business persona .md templates
│ │ └── business/ # Domain-specific business prompts
│ ├── orasaka-tools/ # Tool callbacks, MCP clients, multi-tier cache
│ ├── orasaka-persistence/ # JPA persistence layer
│ │ ├── app/ # Chat sessions, async jobs, model catalog
│ │ └── identity/ # User credentials, authorities, reset tokens
│ ├── orasaka-interceptors/ # Pipeline filter submodules
│ │ ├── orasaka-interceptor-context/
│ │ ├── orasaka-interceptor-enrichment/
│ │ ├── orasaka-interceptor-translation/
│ │ ├── orasaka-interceptor-reformulation/
│ │ ├── orasaka-interceptor-tooling/
│ │ └── orasaka-interceptor-validation/
│ └── orasaka-test-support/ # Shared test infra: Testcontainers, GovernanceRules
│
├── orasaka-apps/ # Runnable applications
│ ├── orasaka-gateway/ # GraphQL, REST, SSE BFF controllers
│ ├── orasaka-ui/ # Client tier workspace (npm workspaces)
│ │ ├── package.json # Workspace root — orchestrates all 5 packages
│ │ ├── orasaka-web-client/ # Next.js 16 client application (:3000)
│ │ ├── orasaka-web-admin/ # SecOps Administration Console (:3001)
│ │ ├── orasaka-mobile-client/ # Expo SDK 53 cross-platform mobile (:8081)
│ │ ├── orasaka-cli/ # TypeScript developer automation CLI
│ │ └── orasaka-shared/ # Shared TS types + Zod validation schemas
│ └── orasaka-workers/ # Async background processors
│ ├── external-services/ # Java Quartz worker (:8082)
│ └── video/ # Python SVD XT GPU worker (:8188)
│
├── orasaka-end2end/ # Hermetic E2E (Java/Web API only — mobile excluded)
├── infra/ # Infrastructure-as-Code
│ ├── docker-compose.yml # Canonical local development infrastructure
│ ├── docker-compose.override.yml # Generated topology overlay (gitignored)
│ ├── local-db/ # Docker init SQL schemas
│ ├── brokers-infra/ # PostgreSQL/RabbitMQ production tuning
│ ├── compute-nodes/ # RunPod/Modal GPU worker Dockerfiles
│ ├── web-backend/ / web-frontend/ # ECS task wrappers
│ └── terraform/ # AWS/RunPod/Modal Terraform modules
│
├── docs/ # Comprehensive project documentation
├── .github/workflows/ci.yml # Split-track CI (backend+web always, mobile path-triggered)
├── pom.xml # Maven reactor root + frontend-maven-plugin (mobile excluded)
└── AGENTS.md # System & Agent Governance Contract
| Module | Location | Purpose |
|---|---|---|
orasaka-core |
orasaka-framework/orasaka-core/ |
Stateless AI orchestration engine. Web-agnostic. Wraps Spring AI under AiClient facade. |
orasaka-identity |
orasaka-framework/orasaka-identity/ |
Pure Java user domain — RBAC, BCrypt passwords, OAuth2 reconciliation. Zero web dependencies. |
orasaka-business |
orasaka-framework/orasaka-business/ |
Business domain context (SovereignWorkflowContext), Markdown persona templates, domain prompts via ResourceLoader. |
orasaka-tools |
orasaka-framework/orasaka-tools/ |
Tool callbacks, MCP client adapters, Caffeine/Postgres multi-tier cache. |
orasaka-persistence |
orasaka-framework/orasaka-persistence/ |
JPA repositories — app/ for chat state and jobs, identity/ for auth tables. |
orasaka-interceptors |
orasaka-framework/orasaka-interceptors/ |
6 independent Maven submodules implementing pipeline interceptor filters. |
orasaka-test-support |
orasaka-framework/orasaka-test-support/ |
Shared test infra: AbstractContainerIntegrationTest, GovernanceRules. |
orasaka-gateway |
orasaka-apps/orasaka-gateway/ |
GraphQL, REST, SSE BFF controllers. Sole module referencing identity + core. |
orasaka-ui |
orasaka-apps/orasaka-ui/ |
Client tier workspace — npm workspaces orchestrating all 5 front-end packages. |
orasaka-web-client |
orasaka-apps/orasaka-ui/orasaka-web-client/ |
Next.js 16 web client — cinematic dark mode, React 19, input-blocking. |
orasaka-web-admin |
orasaka-apps/orasaka-ui/orasaka-web-admin/ |
SecOps Administration Console — isolated on port 3001. |
orasaka-mobile-client |
orasaka-apps/orasaka-ui/orasaka-mobile-client/ |
Expo SDK 53 cross-platform mobile app — 6-screen SaaS boilerplate. |
orasaka-cli |
orasaka-apps/orasaka-ui/orasaka-cli/ |
TypeScript developer CLI with offline SQLite job queue. |
orasaka-shared |
orasaka-apps/orasaka-ui/orasaka-shared/ |
Shared TypeScript types and Zod validation schemas. |
orasaka-workers |
orasaka-apps/orasaka-workers/ |
Async background processors — Java Quartz (:8082) and Python SVD XT (:8188). |
orasaka-end2end |
orasaka-end2end/ |
Hermetic E2E: Java/Web Gateway API validation only. httpyac contracts → CLI Vitest → Playwright Java. Mobile out of scope. |
| Capability | Details |
|---|---|
| Hexagonal Architecture | Enforced at compile time by ArchUnit — GovernanceTest validates 15+ ring rules on every build. |
| Dynamic Interceptor Chain | 15 pipeline filters loaded via Spring AutoConfiguration, independently testable, hot-swappable. |
| Frontend Maven Integration | frontend-maven-plugin runs npm ci and npm run build inside the Maven lifecycle — web targets only, mobile explicitly bypassed. |
| Split-Track CI | Track A (backend+web) always runs full 5-phase pipeline. Track B (mobile) triggers only on path changes — lightweight ESLint + tsc --noEmit. |
| Quantum Validation | Configurable 4-tier validation matrix — JSON Schema → MCP Sandbox → Multi-Agent Debate → Test-Driven Response. |
| Hermetic E2E Pipeline | 3-tier test pyramid: httpyac API contracts → CLI Vitest → Playwright Java UI, orchestrated via orasaka-end2end (ADR-040). |
| Git PromptOps | Persona prompts stored as .md templates in Git — versioned, reviewable, diff-able. |
| Offline-First CLI | Agent commands queued in local SQLite for offline resiliency, synced via 15-second heartbeat. |
| SaaS Mobile Boilerplate | Production-ready 6-screen Expo app — auth lifecycle, subscription tiers, SSE streaming terminal. |
| Data Sovereignty | Every AI call verified against localhost / RFC 1918 / Docker internal addresses. Sovereign DNS Resolution enforced. |
Read in this order for fastest ramp-up:
| # | Document | Purpose |
|---|---|---|
| 1 | Developer Onboarding (101) | Core concepts, architecture map, getting started |
| 2 | Architecture Reference | System topology, BFF schemas, execution flows |
| 3 | Core Deep-Dive | Engine pipeline, interceptor chain, configuration keys |
| 4 | API Reference | Endpoints, parameters, schemas, RBAC constraints |
| 5 | Auth & Security | Authentication flows — local, OAuth2, password recovery |
| 6 | Model Catalog | Tested models: Speech, Image, Video, Vision, Audio, Code |
| 7 | Automation & Workers | Background workers, Quartz, Local Agent Protocol |
| 8 | CLI Reference | Complete command-line interface guide |
| 9 | Business Playbook | Building a product on Orasaka (CinePulse case study) |
| 10 | E2E Testing | Test pyramid, Testcontainers, Playwright, ArchUnit |
| 11 | Deployment (IaC) | Production deployment on AWS, RunPod, Modal |
| 12 | Feature Matrix | Complete feature inventory and delivery status |
| 13 | ADR Index | Architectural Decision Records log |
| 14 | Glossary | Environment variables, terms, naming conventions |
| — | Governance Contract | Module boundaries, ERR codes, agent compliance rules |
Extending the pipeline is a first-class citizen in Orasaka:
- Create a Maven submodule under
orasaka-framework/orasaka-interceptors/. - Implement the
PromptContextInterceptorinterface. - Register via
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. - Scaffold instantly:
npx orasaka generate→ select "🔗 Interceptor".
For concrete instructions, see Build Interceptors.
All pull requests must pass governance checks before merge:
# Full compile + test + format verification (includes frontend-maven-plugin web builds)
./mvnw clean verify
./mvnw spotless:check
# Run only governance constraints (fast feedback)
./mvnw clean test -pl orasaka-framework/orasaka-core -Dtest=GovernanceTest
# Frontend lint + test (web targets only)
npm run validate --prefix orasaka-apps/orasaka-ui/orasaka-web-client
npm run validate --prefix orasaka-apps/orasaka-ui/orasaka-cli
# Mobile validation (lightweight — ESLint + TypeScript typecheck)
cd orasaka-apps/orasaka-ui/orasaka-mobile-client && npx tsc --noEmitCI Pipeline: The split-track CI runs Track A (backend + web) on every push/PR, and Track B (mobile validation) only when
orasaka-mobile-client/,orasaka-shared/, or workspacepackage.jsonfiles change.
This project is licensed under the terms of the LICENSE.md file.
Built with precision — Java 21, Spring AI, Virtual Threads, and zero compromises on sovereignty.