⚡️ ThorAPI — Deterministic Code Generation for Sovereign Systems

ThorAPI turns OpenAPI specs into secure, production-ready backend services and client SDKs.

It’s the open-source backbone of Valkyr Labs’ “Reverse SaaS” architecture — where developers own the code, the data, and the keys.

⸻

🧭 Overview

ThorAPI is a spec-driven code generator that transforms OpenAPI YAML definitions into: • Java Spring Boot microservices with RBAC, JWT, ACL, and SecureField integration. • TypeScript/React client SDKs generated via Swagger templates. • Optional React-Native frontends (coming soon). • Auto-wired ValkyrAI workflow JSONs for end-to-end agentic orchestration.

It’s built for determinism, auditability, and sovereignty — every line of code it emits is reproducible from a known spec and template revision.

⸻

🏗️ Architecture

OpenAPI Spec → ThorAPI Core → Templates → Generated Backend / SDK / Workflow
↑ │ │ ↓
Bundles/Specs → Assembler → Enhancer → api-out.yaml + Generated Code

Core Concepts • Spec-First: Define your API in openapi/api.yaml. • Bundle Assembly: Merge reusable schema bundles and object models dynamically. • Enhancement: Apply intelligent type inference, encryption directives, ACL injection, and more. • CodeGen: Generate Spring Boot + TypeScript SDKs using deterministic templates.

⸻

🧩 Bundle Assembly Workflow

ThorAPI supports assembling modular bundles (schemas, paths, components) before generation.

1. src/main/resources/openapi/api.yaml is read-only — it defines your REST surface.
2. A bundles/ directory beside it contains fragment specs (e.g., user.yaml, invoice.yaml, etc.).
3. During build, ThorAPI merges the bundles into a temporary thorapi-assembled-.yaml.
4. Enhancements are applied, producing the final api-out.yaml.
5. Only the enhanced output is written back to disk — the temp file is transient and deleted on JVM exit.

Enable Assembly

export THORAPI_ENABLE_BUNDLES=true

or

mvn spring-boot:run -Dthorapi.enableBundles=true

or programmatically:

ThorAPI.setBundleAssemblyOverride(true);

ThorAPIController enables this automatically during generation requests.

⸻

🔐 Security by Design

ThorAPI enforces field-level security and auditable access control out of the box.

Feature Description SecureField Annotations Built-in encryption for PII/PHI/PCI fields, integrated with SecureField KMS. RBAC + ACLs Compatible with ValkyrAIPermissionEvaluator and Spring Security @EnableMethodSecurity. JWT Auth Generated endpoints include login, token refresh, and tenant isolation. Audit Logging Automatic WebSocket event streams for runtime traceability.

⸻

⚙️ Example Usage

git clone https://github.com/valkyrlabs/thorapi.git cd thorapi mvn clean install

Place your OpenAPI spec in:

src/main/resources/openapi/api.yaml

Then run:

java -jar target/thorapi.jar generate

Outputs: • api-out.yaml (enhanced spec) • /generated/ Spring Boot backend • /generated-sdk/ TypeScript client • Optional /workflow/ ValkyrAI JSON

⸻

🚀 Quick Start (Docker)

docker run -it --rm
-v $(pwd)/my-specs:/app/specs
-v $(pwd)/output:/app/output
valkyrlabs/thorapi:latest

⸻

🧠 Integration with the Valhalla Suite

Component Role

• ValkyrAI Executes workflows generated by ThorAPI (OpenAPI → AI orchestration).
• SecureField KMS Provides encryption and key management for generated fields.
• ValorIDE Automates PRD execution and project generation via ThorAPI CLI or API.
• GridHeim Offers spreadsheet-native models for dynamic data and formulas.

ThorAPI is open source (ALv2); enterprise security and hosted orchestration layers are part of ValkyrAI Commercial.

⸻

🧪 Example: Generating a Secure API

# openapi/api.yaml
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          x-securefield: encrypt
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: OK

Run ThorAPI:

java -jar thorapi.jar generate

Generated Spring Boot model:

@SecureField private String email;

⸻

🔧 Configuration

Property Default Description thorapi.enableBundles false Enables bundle assembly thorapi.outputDir ./generated Destination for generated code thorapi.specPath ./src/main/resources/openapi/api.yaml Path to input spec thorapi.templateDir embedded Template set for codegen thorapi.enhancers DefaultEnhancer Custom enhancement chain

⸻

💡 Developer Notes • Built with Java 21, Spring Boot 3.x, and Swagger Codegen. • Compatible with Maven Central io.valkyr:thorapi-core. • Use alongside ValkyrAI CLI for automated code-to-workflow generation.

⸻

🛡️ License • Core engine and templates are AGPL 3.0. • Generated code is MIT Licensed (you own what you generate). • Advanced key management and workflow integration available under ValkyrAI Commercial License.

⸻

🌍 Community & Support • 📚 Docs: https://valkyrlabs.com/docs/thorapi • 💬 Discussions: https://github.com/valkyrlabs/thorapi/issues • 🧰 Join the Reverse SaaS Builders movement at https://valkyrlabs.com • 🧙‍♂️ Built by John McMahon and the Valkyr Labs Collective

⸻

ThorAPI — because real power is owning the forge that builds your systems.