AppFactory

Define the product. Automate the engineering.

A RAIDER-governed software delivery control plane for generating, validating and provisioning real applications through reusable blueprints and secure GitHub workflows.

Why AppFactory · Architecture · Blueprints · Quick start · Security · Documentation · API · Project status

---

Why AppFactory

Launching a new application should not mean rebuilding the engineering workflow from scratch. A repository needs code, but it also needs a tested starting point, scoped credentials, quality gates, ownership boundaries and a reliable path from specification to delivery.

AppFactory turns a reviewed project specification into an appropriately governed repository. It does the repetitive platform work once, so each team can concentrate on product-specific behavior.

• Specify, don't copy. Choose a versioned blueprint or a native landing-generation path through an explicit request contract.
• Provision with guardrails. GitHub Actions OIDC and GitHub App identities authorize privileged operations; knowing a URL is not sufficient.
• Keep infrastructure intentional. Generic API, webapp, desktop and mobile presets don't silently create billable cloud resources or choose a production database.
• Make quality portable. Reusable CI, Project Automation, and product README assurance come from shared services—not ad hoc repository copies.
• Reconcile safely. Idempotent operations and ownership markers protect existing projects against accidental destructive reprovisioning.

Delivery architecture

flowchart TD
  A["Reviewed project request"] --> B["Trusted GitHub Actions workflow"]
  B --> C["OIDC identity verification"]
  C --> D["AppFactory orchestration · Cloudflare Worker"]
  D --> E{"Project type / preset"}
  E --> F["Native landing renderer"]
  E --> G["Versioned service / webapp / desktop / Android blueprint"]
  E -. "Experimental path" .-> X["OpenPage adapter POC"]
  F --> H["GitHub repository lifecycle"]
  G --> H
  H --> I["Quality gates + Project Automation"]
  I --> J{"Approved delivery model"}
  J --> K["Cloudflare Pages / Workers (supported flows)"]
  J --> L["Consumer-managed hosting or desktop/mobile build"]

Loading

The diagram describes the platform's delivery boundaries, not a claim that every project type is deployed automatically. External OpenPage generation is still isolated from the production provisioning route.

Blueprint catalog

Project family	Supported foundation	Provisioning behavior
Landing websites	Native brief → Manifest v2 → modular renderer	Repository generation and the configured Cloudflare Pages delivery path
API & backend services	Node.js 24 / TypeScript; specialized entitlements preset	Generic API blueprint stays cloud-neutral; the entitlements preset has its own reviewed Worker/D1 delivery model
Web applications	React 19 / TypeScript / Vite	Repository + CI + Project Automation; hosting and auth remain product decisions
Windows desktop	Tauri 2 / Rust / React	Native app foundations and CI; no Cloudflare Pages assumption
Android mobile	Jetpack Compose + test/CI baseline	Android repository and governed workflow; no implicit app-store release

Implementation details live in service, webapp, desktop and Android blueprint contracts. The README quality contract covers product documentation independently of the application runtime.

Quick start

Local development (Node.js and the repository dependencies required):

npm install
npm run typecheck
npm run dev

Provisioning a Trigenys project is an authorized GitOps workflow, not an unauthenticated public API call:

1. Add a reviewed manifest to .appfactory/requests/<slug>.json in this repository.
2. Select the supported projectType and preset, including the desired visibility and product-specific description.
3. Merge the reviewed request into main; the provisioning workflow authenticates to AppFactory and creates or reconciles the repository.
4. Inspect the resulting repository, its CI and AppFactory Project Automation configuration before adding product infrastructure.

A minimal generic API service request looks like:

{
  "name": "Example Service",
  "slug": "example-service",
  "projectType": "service",
  "preset": "typescript-api",
  "private": true,
  "description": "A customer-specific API with separately governed infrastructure."
}

This request does not deploy a database or production server for the generic preset. Use the project request and service blueprint documentation before assuming a delivery route.

Security model

Mutation endpoints are protected operations. AppFactory validates short-lived GitHub Actions OIDC tokens, expected audience, allowed repository and branch, and the exact trusted workflow identity. GitHub App permissions control repository lifecycle; cloud credentials remain on the Cloudflare side instead of being distributed to every consuming repository.

• Authorization is bound to caller/workflow identity—not to a plain repository name supplied in a payload.
• Secrets never belong in request manifests, README examples or public CI logs.
• Unowned brownfield resources are not silently adopted. Reconciliation must be explicit and idempotent.
• Cloudflare resource authorization and Workers Builds authorization remain separate where provider constraints require it.

See mutation authentication, brownfield Pages, and TypeScript Worker runtime.

Engineering governance

AppFactory implements the RAIDER engineering approach—Reusable, Agnostic, Idempotent, Durable, Engineering-grade, Retroactive—as enforceable platform contracts, rather than merely a README slogan.

• AppFactory owns blueprints, orchestration, provenance and repository/documentation quality.
• AppFactory Project Automation owns GitHub Project synchronization, priorities and issue lifecycle.
• Project Registry owns the canonical product/capability inventory.
• Trigenys Engineering OS owns shared engineering guidance and skills.

This README also uses AppFactory's own presentation and quality contract, recorded in .appfactory/readme-contract.json. Future changes to its managed introduction must remain non-destructive and pass the same read-only audit as consuming repositories.

Maturity and boundaries

Active beta: real provisioning and CI capabilities, with clearly bounded experiments. Existing generic blueprints, OIDC checks, repository creation and CI are implemented. Not every preset provisions runtime infrastructure; external engine rendering/export and some brownfield workflows remain under development or are scoped to specific recipes.

A successful repository bootstrap is not evidence that the generated product's business logic is implemented, that its security has been independently certified, or that it has been deployed. Features labeled experimental stay behind explicit validation boundaries.

Generation engines — native and OpenPage proof of concept

AppFactory has a native brief-to-manifest pipeline and modular landing renderer. The OpenPage integration explores a pluggable generation-engine boundary without absorbing the external project's renderer or treating the proof of concept as production-ready.

Landing-generation path:

brief
  -> AppFactory orchestration
  -> generation engine
       -> native AppFactory planner (production path)
       -> OpenPage adapter (POC path)
  -> quality gate
  -> repository generation
  -> Cloudflare Pages deployment

The first external engine POC targets buildingopen/openpage, an MIT-licensed JSON-first website builder. OpenPage generates a structured site config from a prompt; AppFactory remains responsible for orchestration, quality rules, GitHub lifecycle and deployment.

API

GET /health

Returns Worker readiness plus the active milestone, manifest version and engine configuration flags without exposing secret values.

POST /projects

Production project provisioning currently uses the native AppFactory renderer.

Preferred request:

{
  "name": "Nova Legal",
  "slug": "nova-legal",
  "brief": "Cabinet d'avocats premium spécialisé dans les startups technologiques en Afrique. L'objectif principal est la prise de rendez-vous.",
  "language": "fr",
  "audience": "Fondateurs et dirigeants de startups technologiques",
  "private": true
}

AppFactory infers a specification such as:

industry  -> legal
tone      -> premium
goal      -> bookings
recipe    -> luxury
animation -> subtle
sections  -> hero, trust, services, process, faq, contact, final-cta

Successful response includes the repository, Manifest v2 commit and Cloudflare Pages deployment details.

The optional request field engine accepts native or openpage. native is the default. engine: "openpage" is deliberately blocked on /projects until OpenPage rendering/export is wired end-to-end, so AppFactory never silently deploys the native template while claiming an external engine was used.

POST /engines/openpage/generate

POC endpoint for validating OpenPage generation independently from repository provisioning.

It accepts the same brief-first request as /projects, calls the configured OpenPage generator and returns a sanitized OpenPage SiteConfig.

AppFactory removes evidence-sensitive block types when the brief does not contain supporting data, including fabricated testimonials, logo clouds, statistics and pricing. It also requires a hero and a CTA/contact block.

Example:

{
  "name": "Nova Legal",
  "slug": "nova-legal-openpage-poc",
  "brief": "Cabinet d'avocats premium spécialisé dans les startups technologiques en Afrique. L'objectif principal est la prise de rendez-vous.",
  "language": "fr",
  "audience": "Fondateurs et dirigeants de startups technologiques"
}

Service project blueprints

AppFactory can provision backend services through projectType: "service". The generic typescript-api preset creates a Node.js 24 + TypeScript service repository with CI, AppFactory Project Automation, release automation and RAIDER guidance while intentionally leaving hosting and persistence to the product. The specialized entitlements preset additionally provisions/reuses D1, wires the real database UUID into Wrangler, creates/reuses the Cloudflare Worker, connects native Workers Builds, runs remote D1 migrations and triggers the first production build.

Service repositories intentionally bypass the landing renderer and Cloudflare Pages. See Service project blueprints for the request contract, Cloudflare delivery path, ownership boundaries and idempotency model.

Manifest v2

The native engine emits structured generation intent:

• strategy: brief, audience, industry, tone and conversion goal
• brand: tone, palette and typography direction
• design: recipe, animation and density
• sections: ordered section plan
• seo: generated title and description
• motion: motion policy and reduced-motion requirement
• content: generated business-facing section content

The native modular renderer consumes this contract directly.

Runtime

AppFactory API is designed for Cloudflare Workers and uses GitHub App installation authentication plus the Cloudflare Pages API.

Required Worker runtime variables/secrets:

• GITHUB_APP_ID
• GITHUB_INSTALLATION_ID
• GITHUB_PRIVATE_KEY
• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN — user-scoped Cloudflare token retained for the Workers Builds API, which does not accept account-owned tokens. It is also the backward-compatible fallback for resource APIs when no dedicated resource token is configured.
• CLOUDFLARE_PAGES_D1_TOKEN — dedicated Cloudflare resource token for Pages, D1 and Worker resource operations. Prefer an account-owned token for automation. Brownfield/service Worker creation requires Workers product-level Admin; existing Worker deployment requires Editor; D1/Pages permissions remain scoped to the resources AppFactory manages.

Optional variables:

• GITHUB_OWNER (defaults to Trigenys)
• GITHUB_TEMPLATE_OWNER (defaults to GITHUB_OWNER)
• GITHUB_TEMPLATE_REPO (defaults to appfactory-landing-template)
• GITHUB_COMMIT_AUTHOR_NAME
• GITHUB_COMMIT_AUTHOR_EMAIL
• GITHUB_WEBAPP_BLUEPRINT_OWNER
• GITHUB_WEBAPP_BLUEPRINT_REPO
• GITHUB_WEBAPP_BLUEPRINT_REF
• GITHUB_OIDC_PROVISIONER_REPOSITORY — optional public provisioning repository; defaults to <GITHUB_OWNER>/.github
• GITHUB_OIDC_PROVISIONER_WORKFLOW_REF — optional exact trusted workflow identity for the public provisioner
• OPENPAGE_GENERATOR_URL — self-hosted OpenPage base URL or full /api/generate URL
• OPENPAGE_API_TOKEN — optional bearer token for a protected Trigenys OpenPage deployment
• CLOUDFLARE_BUILD_TOKEN_UUID — optional existing Workers Builds token UUID when automatic discovery is ambiguous
• CLOUDFLARE_BUILD_TOKEN_SOURCE_WORKER — optional Worker used to discover an existing build token; defaults to appfactory-api
• ENVIRONMENT

GitHub downloads App private keys as PEM files. AppFactory accepts both the native GitHub RSA PEM format (-----BEGIN RSA PRIVATE KEY-----) and PKCS#8 (-----BEGIN PRIVATE KEY-----) directly, so no manual key conversion is required. The legacy GITHUB_PRIVATE_KEY_PKCS8 secret name remains supported as a fallback.

Commit attribution

Generated commits use the human project owner as the Git author and the AppFactory GitHub App as the technical committer. The default author is the EagleFox31 GitHub account via its GitHub noreply address; the optional commit-author variables can override that identity.

Cloudflare GitHub access

The Cloudflare Workers & Pages GitHub App must be installed on the Trigenys organization with access to repositories generated by AppFactory. For end-to-end unattended generation, granting that Cloudflare App access to all current and future repositories in the organization avoids a manual authorization step for every generated site.

Each native Pages project is created with:

• Git provider: GitHub
• production branch: main
• build command: npm run build
• output directory: dist
• production deployments enabled
• preview deployments enabled for branches

Continuous deployment

AppFactory uses Cloudflare Workers Builds with the native GitHub integration for production delivery. The existing appfactory-api Worker is connected directly to Trigenys/appfactory, so pushes to the configured production branch are built and deployed by Cloudflare without duplicating Cloudflare account credentials into GitHub Actions.

GitHub Actions remains responsible for repository validation (CI), while Cloudflare reports its own Workers Builds: appfactory-api check run back to the same commit.

Production runtime credentials remain owned by the Worker in Cloudflare:

• GITHUB_PRIVATE_KEY
• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID
• the other AppFactory runtime variables documented above

No repository-level CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is required for normal deployment.

The npm run deploy / wrangler deploy path is retained only as a break-glass/manual deployment path. Because wrangler.jsonc sets keep_vars: true, a manual Wrangler deployment preserves dashboard-managed runtime variables.

Local development

npm install
npm run typecheck
npm run dev

Store local secrets in .dev.vars; never commit that file.

Architecture boundary

appfactory owns orchestration, engine selection, quality gates, repository generation and hosting provisioning.

appfactory-landing-template is the native fallback renderer, not the only long-term generation engine.

External generation engines such as OpenPage plug into AppFactory behind adapters. Their own renderer/export path should remain authoritative wherever possible instead of being reimplemented inside the Worker.

See docs/openpage-engine-poc.md for the OpenPage audit and the remaining end-to-end integration step.

Desktop project blueprints

AppFactory can provision Windows desktop repositories through projectType: "desktop", platform: "windows" and preset: "tauri-react". The versioned blueprint lives in blueprints/tauri-react/ and includes Tauri 2, React/TypeScript/Vite, a narrow Rust native boundary, CI and AppFactory Project Automation.

Desktop repositories bypass Cloudflare Pages and Workers provisioning. See Desktop project blueprints.

Web application blueprints

AppFactory can provision general React web applications through projectType: "webapp" and preset: "react-vite". The versioned blueprint lives in blueprints/react-vite/ and includes React 19, TypeScript, Vite, Node.js 24 CI and AppFactory Project Automation.

The webapp blueprint intentionally does not assume a hosting provider, backend, authentication system or persistence layer. Product requirements decide those boundaries after provisioning. See Web application blueprints.

Mobile project blueprints

AppFactory can provision native Android repositories through projectType: "mobile", platform: "android" and preset: "android-compose". The versioned blueprint lives in blueprints/android-compose/ and includes Compose UI foundations, CI, AppFactory Project Automation and Roborazzi visual-regression support.

Mobile repositories bypass Cloudflare Pages and Workers provisioning. See Mobile project blueprints.

Mutation authentication

Production mutation endpoints are authenticated with GitHub Actions OIDC. Knowing the Worker URL is not sufficient to create repositories or invoke generation.

Use the Provision AppFactory Project workflow in .github/workflows/provision-project.yml. The Worker validates the short-lived GitHub token signature, audience, repository, main ref and exact workflow identity before accepting POST /projects or POST /engines/openpage/generate.

See Mutation authentication.

Brownfield Worker self-service

Existing Trigenys repositories can provision their own Cloudflare Worker without receiving the AppFactory Cloudflare credentials. The historical Python/Pywrangler path remains the default, and repositories can now explicitly select the reusable typescript-wrangler runtime for TypeScript/Hono-style APIs.

The repository must call POST /infrastructure/worker from the exact workflow:

<repository>/.github/workflows/appfactory-infrastructure.yml@refs/heads/main

Authentication is a short-lived GitHub Actions OIDC token with audience appfactory-api. AppFactory validates the token signature, organization, protected main ref and exact workflow identity. The caller may provision only the repository named by its own OIDC claim.

The brownfield recipes are deliberately narrow:

• Worker name is derived from the repository: <repo>-api;
• root directory is /backend;
• omitted runtime preserves the reviewed Python/Pywrangler recipe;
• runtime: "typescript-wrangler" selects the reviewed Node/TypeScript recipe (npm ci --ignore-scripts && npm run check then local Wrangler deploy);
• build/deploy command mixing or arbitrary commands are rejected;
• Worker runtime secret names must use the repository prefix;
• an existing Worker without an AppFactory ownership marker is never silently adopted;
• AppFactory deliberately separates Cloudflare resource authorization from Workers Builds authorization: resource calls prefer CLOUDFLARE_PAGES_D1_TOKEN, while /builds/* calls keep using the user-scoped CLOUDFLARE_API_TOKEN. This matches Cloudflare's current API constraint that Workers Builds requires a user-scoped token. Creating a brand-new Worker uses the explicit Worker resource API and requires Workers product-level Admin; bootstrap code is uploaded only after the resource exists. If bootstrap upload fails, AppFactory removes the empty Worker so retries stay idempotent.

This keeps CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID out of product repositories. Product-specific secrets may cross the authenticated OIDC request and are written directly to that product's Worker; AppFactory never returns secret values.

See TypeScript/Wrangler brownfield Worker runtime for the reusable runtime contract.

Brownfield Pages self-service

Existing Trigenys repositories can provision a secondary Cloudflare Pages site through POST /infrastructure/pages from the canonical .github/workflows/appfactory-infrastructure.yml workflow.

The endpoint keeps Cloudflare credentials inside AppFactory, verifies the caller repository through GitHub Actions OIDC, creates or reconciles the GitHub-connected Pages project, applies repository-owned build settings, optionally attaches a custom domain and records ownership in .appfactory/pages-infrastructure.json.

This allows a mobile, desktop, service or webapp repository to expose a public landing or documentation surface without changing its primary AppFactory project type. External DNS remains an explicit boundary: AppFactory returns the required CNAME target when the authoritative DNS provider is outside Cloudflare.

See Brownfield Cloudflare Pages.

Environment-aware Cloudflare infrastructure

Brownfield Worker and Hyperdrive self-service accepts an optional environment of production or staging (default production). Production identity remains backward compatible. Staging uses isolated deterministic identities:

Worker:     <repo>-staging-api
Hyperdrive: <repo>-staging
DB profile: <repo>-staging
markers:    .appfactory/worker-infrastructure.staging.json
            .appfactory/hyperdrive.staging.json

Database credentials still live only in AppFactory's central HYPERDRIVE_DATABASE_PROFILES; callers never submit host/user/password fields.