AppStruct
AppStruct is a configuration-driven Rust full-stack application generator. It compiles a multi-file YAML App Spec into a typed IR, PostgreSQL migrations, an Axum/SeaORM backend, OpenAPI, a TypeScript client, and a React/Vite application.
The repository is currently a technical preview. It is distributed from a source checkout for now;
there is no crates.io package or binary installer yet. M0-M6 are complete, including production builds,
the coordinated development server, Tenant/Audit/Mail/Jobs/File modules, the locked
appstruct/saas@1 preset, transactional project updates, and a runnable SaaS template and example.
The SaaS preset includes an Admin operations overview and guarded Jobs retry/replay controls;
Billing remains out of scope for preset version 1.
Quick Start
The workspace pins Rust 1.98.0. Install the CLI from this checkout:
Create a minimal project backed by an existing PostgreSQL database:
Update DATABASE_URL in .env before running doctor. For a Docker-managed PostgreSQL
development database, use --template dashboard or --template saas and ensure Docker Compose
is available.
appstruct dev starts the generated API and Vite, watches App Spec and user Rust inputs, and
stops its child processes on Ctrl-C. Managed databases default to prompting only when migrations
are required; external databases default to leaving migrations entirely to the operator.
The default URLs are http://127.0.0.1:3000 and http://127.0.0.1:5173.
Generated Web applications use a pinned modern baseline: React 19, TypeScript, and Vite with TanStack Query, TanStack Router, TanStack Table, and TanStack Form plus Zod validation. The generated dependency lockfile is part of the project output, so installs and builds remain repeatable across machines.
Configure development migration ownership explicitly when needed:
database:
provider: postgres
dev:
mode: managed
migration: prompt # auto | prompt | never | unmanaged
auto creates and applies safe migrations, prompt asks only when work is pending, never
performs read-only compatibility checks and blocks stale schemas, and unmanaged skips all
AppStruct migration checks before starting. Production backend startup never runs migrations;
use a dedicated migrate status / migrate apply release step.
Create a review-only App Spec draft from an existing PostgreSQL schema:
The command reads DATABASE_URL, never changes the database or root includes, and refuses to
overwrite the output. Review unsupported-shape warnings and add explicit entity access rules before
including the draft in appstruct.yaml.
Generated list endpoints offer offset pagination with totals and primary-key cursor pagination for large result sets. A filterable relation can traverse one hop to target fields that are also marked filterable, while retaining target access and tenant scopes. Each resource also exposes bounded count/sum/average/min/max and group-by queries over filterable fields. See Generated resource queries for request, response, OpenAPI, and TypeScript client contracts. Fields can additionally declare independent read/write access rules; unauthorized response fields are omitted and unauthorized submitted fields are rejected by the backend.
Composite and partial indexes are declared per entity with indexes; see
Schema indexes.
Named entity seed rows are declared with seeds and included in reviewable migrations; see
Seed data.
Enable tenant isolation together with Auth and mark each tenant-owned entity explicitly:
modules:
auth:
enabled: true
user_entity: User
tenant:
enabled: true
entities:
Project:
tenant: true
The generated Web application provides organization onboarding and switching. Generated clients
send X-AppStruct-Tenant; the backend validates membership and injects tenant_id into every
tenant-scoped CRUD query and write.
Enable Audit with Auth, choose the reader roles, and opt entities into transactional snapshots:
modules:
audit:
enabled: true
reader_roles:
entities:
Project:
audit: true
Create, update, and delete snapshots are committed in the same PostgreSQL transaction as the business write. The generated Audit page and read-only API enforce reader roles and current-tenant isolation.
Mail supports compile-time validated templates and capture, SMTP, or Resend providers. Provider
credentials remain in server environment variables, and business handlers can call the generated
RequestContext::send_mail capability. Capture is development-only and rejected in production.
Select the official SaaS preset to enable the implemented modules with one versioned contract:
preset:
name: appstruct/saas
version: 1
The project must commit an appstruct.lock containing the preset digest and exact module versions.
User modules mappings override defaults recursively; scalar and list values replace their defaults.
Inspect the locked contract with appstruct preset show or print the effective module
configuration after project overrides with appstruct preset show --expanded. Admin is available
as an operations preview with Jobs recovery controls; Billing is not part of preset version 1.
Commands
appstruct new <name> --template minimal|dashboard|saas
appstruct schema
appstruct check [--deny-warnings] [--format text|json]
appstruct generate [--check]
appstruct migrate plan|dev|lint|apply|status
appstruct dev [--api-port <port>] [--web-port <port>]
appstruct build
appstruct doctor [--format text|json]
appstruct db pull [--schema <name>] [--output <project-relative-path>]
appstruct auth bootstrap-admin --email <address>
appstruct preset show [--expanded]
appstruct update
migrate plan is read-only. migrate dev --accept creates and optionally applies only
non-destructive online migrations. Production deployment uses migrate status followed by
the explicit migrate apply command. migrate lint reports destructive, locking, and unsafe
non-null changes without writing files; use --deny-warnings in CI to enforce operational review.
Documentation
- Installation
- Upgrading
- Deployment
- Generated resource queries
- Schema indexes
- Seed data
- Releasing
- Next product roadmap
- Product requirements
- Technical design
The references/ directory contains local research material and is intentionally excluded
from version control and product commits.
Development
Run the repository quality gates with the pinned local toolchain:
Run the PostgreSQL browser gate against a dedicated test database:
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_tenant_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_audit_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_mail_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_jobs_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_file_e2e' \
APPSTRUCT_E2E_DATABASE_URL='postgresql://user:password@127.0.0.1/appstruct_saas_e2e' \
Rust source files are limited to 400 lines by a repository test. Generated projects also pin their Rust and pnpm dependency graphs so repeated generation and production builds remain reviewable and reproducible.
Before committing or pushing a change, inspect the worktree and run the checks that match the files you changed:
Do not commit local secrets or generated machine state. In particular, keep .env files (except
intentional .env.example templates), private keys and certificates, node_modules/, target/,
references/, Playwright reports, and test-results/ out of Git. The repository .gitignore
already excludes these paths; verify tracked, untracked, and ignored state before the first push.
License
Workspace crates are licensed under MIT OR Apache-2.0.