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/SQLx + sift-query backend, OpenAPI, a TypeScript client, and a React/Rsbuild application.
The repository is currently a technical preview. Build the CLI from this source checkout to use
the current implementation. 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 runnable templates. The SaaS preset
includes an Admin operations overview and guarded Jobs retry/replay controls. Generated
applications can opt into Stripe Billing v1; it remains disabled in preset version 1.
Requirements
The Dev Container first run requires Docker and VS Code with Dev Containers on the host. The versions below are supplied inside the container; install them locally only when using the non-container path.
| Dependency | Version | Used for |
|---|---|---|
| Rust | 1.99.0 with rustfmt and Clippy | CLI and generated backend |
| PostgreSQL | 17 recommended | migrations and generated API |
| Node.js | 24 recommended | generated Web application |
| pnpm | 11.25.0 | locked Web dependency installation |
| Docker Compose | Current release, optional | database.dev.mode: managed only |
The workspace and every generated project pin the Rust toolchain. Generated Web apps also commit a pnpm lockfile so installs and builds stay reproducible. Release installers are documented in Installation.
Install the CLI
From the repository root:
Use target/release/appstruct directly, or copy it onto an existing PATH directory:
Keep --locked so Cargo uses the committed workspace Cargo.lock.
cargo install --path crates/appstruct-cli is not the reproducible install path in this layout.
Quick start
The recommended first run uses the included Dev Container. Open this repository in VS Code with the Dev Containers extension, then choose Reopen in Container. The container builds the CLI and starts PostgreSQL; after setup finishes, run:
appstruct dev opens the generated Web application after forwarded port 5173 is ready. The API
uses forwarded port 3000. This path
requires Docker and VS Code with Dev Containers on the host, but no host Rust, Node.js, or
PostgreSQL installation. See Installation for details.
For a local installation, pick one template. minimal uses a database you already run;
dashboard and saas can start managed PostgreSQL through Docker Compose.
Run appstruct init in a terminal to choose a project name and template. For scripts, pass both
inputs with appstruct init <name> --template minimal|dashboard|saas, or use appstruct new as
shown below. init also accepts --database-mode external|managed, --api-port, and
--web-port; the ports are saved in the project's ignored .env. Authentication and tenant
capabilities currently follow the selected template. Project creation prints the next commands.
Existing PostgreSQL
See the existing database guide for catalog import, access review and the first run.
Edit DATABASE_URL in .env, then:
External databases default to database.dev.migration: unmanaged, so run migrations before the
first start. appstruct dev then generates and builds the backend, installs locked Web dependencies,
starts the API and Rsbuild, and opens the Web application when it is ready. The default URLs are
http://127.0.0.1:3000 and http://127.0.0.1:5173; override them with --api-port and
--web-port, or pass --no-open to keep the browser closed.
Managed PostgreSQL
The dashboard template includes compose.yaml and lets AppStruct manage PostgreSQL:
Managed mode starts only the Compose postgres service. Services started in this session stop on
Ctrl-C; named volumes are kept. Already-running services are left running. Managed mode defaults
to database.dev.migration: prompt and asks only when work is pending.
SaaS preset
The template locks appstruct/saas@1 with Auth, Tenant, Audit, Mail, Jobs, and File. After
registration, create an organization and use the tenant-isolated, audited Project and Task
resources. Development uses capture mail, local files under .appstruct/files, and PostgreSQL
for Jobs/Outbox.
The first registered user is a member. Provision an admin once from a trusted host:
Commit appstruct.lock; it stores the preset digest and exact module versions. Inspect overrides
with appstruct preset show --expanded.
Import an existing schema
Create a review-only App Spec draft from a live 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 entity access rules before
including the draft in appstruct.yaml. Use --access public|authenticated,
--access role --role <name>, or --access owner --owner <relation> to write a uniform reviewed
policy; the default remains fail-closed. Use --check in CI, or --diff to print live changes
without writing the file.
Development migrations
Declare database ownership and migration behavior in appstruct.yaml:
database:
provider: postgres
dev:
mode: managed
migration: prompt # auto | prompt | never | unmanaged
autocreates and applies safe online migrations.promptasks only when work is pending.neverruns read-only compatibility checks and blocks stale schemas.unmanagedskips AppStruct migration checks; the operator owns the database.
mode: managed starts local Compose PostgreSQL. mode: external never starts or stops it.
Production backend startup never runs migrations; use migrate status and an explicit
migrate apply in the release.
Generated capabilities
The Web runtime is pinned to React 19, TypeScript, Rsbuild/Rspack, and Rstest, with TanStack Query, Router, Table,
and Form with shared valueError validation. Resource APIs support offset and cursor pagination, filters, sorts, relation
filters, aggregates, and group-by queries, all under actor, resource, and tenant policy.
Other contracts live in dedicated guides:
- Resource queries, schema indexes, and seed data
- Auth, Tenant, Audit, Mail, Jobs, and File modules
- Bulk operations, saved views, soft delete, invitations, email verification, OAuth/OIDC, and personal API tokens
- Generated Axum/SQLx + sift-query backend, OpenAPI, and TypeScript client
Commands
appstruct init [<name>] [--template minimal|dashboard|saas] [--database-mode external|managed] [--api-port <port>] [--web-port <port>]
appstruct new <name> --template minimal|dashboard|saas
appstruct schema
appstruct capabilities [--format text|json]
appstruct check [--deny-warnings] [--format text|json]
appstruct generate [--check] [--timings]
appstruct migrate plan|dev|lint|apply|status
appstruct dev [--api-port <port>] [--web-port <port>] [--no-open]
appstruct build
appstruct doctor [--format text|json]
appstruct status [--format text|json]
appstruct project status|events|diagnose
appstruct db pull [--schema <name>] [--output <path>] [--review | --check | --diff] [--access <policy>]
appstruct auth bootstrap-admin --email <address>
appstruct preset show [--expanded]
appstruct update
migrate plan is read-only. migrate dev --accept creates and may apply only non-destructive
online migrations. Production uses migrate status then explicit migrate apply. migrate lint
reports destructive, locking, and unsafe non-null changes; use --deny-warnings in CI.
appstruct generate --timings prints compiler, planner, formatter, cache-hit, and output costs.
Documentation
Each guide has an English source and a Simplified Chinese translation (*.zh-CN.md). The static
site in site/ renders both languages; from the workspace root run pnpm run site:dev.
Start here
Build and delivery
- Deployment
- Releasing
- Repository quality gates
- Security headers
- Migration lint
- Module registry
- Delivery optimization
Data modeling
- Generated resource queries
- Lossless scalar values and datetime controls
- Schema indexes
- Seed data
- Aggregate line items
- Relation display
- Soft delete and history
- Saved views
Application design
- Headless Web controllers
- Business UI semantics
- Bulk operations
- Entity workflows
- Reports
- Record activity
Platform modules
- Email verification
- Organization invitations
- OAuth and OIDC
- Generated application billing
- Personal API tokens
- Realtime events, presence, and edit leases
- Interval schedules
- Signed webhooks
Operations
- Operations Admin console
- Metrics and database workloads
- Chromium report renderer
- Production report renderer adapter RFC
- Operations Demo findings
Project records
The references/ directory contains local research material and is excluded from version control.
Quality checks
Run repository gates with the pinned toolchain. Advisory checks need cargo-deny 0.20.2 or newer:
PostgreSQL browser tests use dedicated databases and the matching scripts/run-*-e2e.sh scripts.
GitHub Actions checks Rust, all three generated Web templates, documentation and key PostgreSQL
regressions on pull requests. Main, weekly, manual and tagged-release runs add the full module,
Docker deployment, renderer isolation, packaging and benchmark gates. See the
quality gate matrix and diagnostics guide.
scripts/run-template-build.sh checks generated Web production dependencies, formatting, tests,
types, and the Rsbuild bundle.
Generated-backend compile tests reclaim their temporary packages while retaining shared dependency
artifacts. M6 E2E scripts remove their suite-specific target on exit; set
APPSTRUCT_KEEP_TEST_TARGETS=1 only when retaining one for debugging. If a run is interrupted before
cleanup, scripts/clean-test-artifacts.sh removes disposable generated-backend, coverage, and package
targets. Pass --all to run cargo clean on the whole workspace.
Before committing:
Do not commit real .env files, passwords, API keys, private keys or certificates,
node_modules/, target/, references/, Playwright reports, or test-results/. Placeholder
values in .env.example may be committed.
Current boundaries
AppStruct is a technical preview. Cutting a GitHub release still requires maintainer remote setup, and production migrations are reviewed and applied as a separate release step. Billing, hosted deployment adapters, and a visual editor are roadmap items, not stable preset v1 promises. Billing is available only when explicitly enabled in a generated application.
License
Workspace crates are licensed under MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.