appstruct-module-sdk 0.2.0

Module manifests and deterministic capability resolution for AppStruct
Documentation

AppStruct

English | 简体中文

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:

rustup toolchain install 1.99.0 --component clippy,rustfmt
cargo build --release --locked -p appstruct-cli
./target/release/appstruct --version

Use target/release/appstruct directly, or copy it onto an existing PATH directory:

install -d "$HOME/.local/bin"
install -m 0755 target/release/appstruct "$HOME/.local/bin/appstruct"
appstruct --version

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 init notes --template minimal
cd notes
appstruct migrate dev --accept
appstruct doctor
appstruct dev

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.

appstruct new notes --template minimal
cd notes
cp .env.example .env

Edit DATABASE_URL in .env, then:

export DATABASE_URL=postgresql://user:password@127.0.0.1:5432/notes
appstruct migrate dev --accept
appstruct doctor
appstruct dev

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:

appstruct new project-hub --template dashboard
cd project-hub
appstruct doctor
appstruct dev

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

appstruct new saas-demo --template saas
cd saas-demo
appstruct preset show
appstruct doctor
appstruct dev

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:

appstruct auth bootstrap-admin --email admin@example.com

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:

appstruct db pull --schema public --output spec/imported.yaml

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
  • auto creates and applies safe online migrations.
  • prompt asks only when work is pending.
  • never runs read-only compatibility checks and blocks stale schemas.
  • unmanaged skips 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

Data modeling

Application design

Platform modules

Operations

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:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo deny check advisories
scripts/run-template-build.sh

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:

git status --short --branch
git diff --check

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.