Build Your First Application

This path uses SQLite, so the first request needs no database container or AWS account. It still follows the same contract, application, adapter, HTTP, planning, and evidence boundaries used by a larger deployment.

RuntimeOne local Rust process

Axum serves the generated API while SQLite provides a real persistence engine.

Cloud changesNone

Every command in this guide is local or a dry run; no AWS account is required.

ArchitectureProduction-shaped

Domain, application, adapter, delivery, configuration, and evidence remain separate.

OutcomeAn inspectable vertical slice

You can run it, call it, add a resource, and trace the result through the project graph.

1. Generate the project

cargo minco new hello-minco --database sqlite
cd hello-minco
cp .env.example .env

The generator creates ordinary Rust, TOML, SQL, and OpenAPI source. Domain and application crates remain independent of Axum, SQLx, Lambda, and AWS SDKs. You can inspect or change every generated file; there is no remote control plane that must remain available for the application to run.

What to inspect

Confirm that the project contains an OpenAPI contract, domain and application boundaries, a SQLite adapter, an HTTP delivery crate, environment configuration, and explicit quality commands.

2. Inspect before running

cargo minco doctor
cargo minco contract check
cargo minco inspect --json

These commands answer different questions:

Command	Question it answers	What it does not prove
doctor	Are the required local tools and project inputs available?	That the application behavior is correct
contract check	Is the OpenAPI document valid for Minco's reviewed boundary?	That implementation and contract are synchronized
inspect --json	How do contract, code, capabilities, resources, and evidence connect?	That any provider resource exists

Use explain when you need the complete trace for one OpenAPI operation:

cargo minco explain getPlatform --json

A successful trace should identify the contract operation and its known implementation, capability, resource, and evidence links. Missing or ambiguous links remain diagnostics instead of being silently guessed.

3. Review the local plan

cargo minco dev --profile sqlite --dry-run --json

The dry run projects the graph into a local execution plan. Review the selected environment, lifecycle stages, process command, ports, migration step, and readiness probe before anything starts.

Dry-run boundary

A dry run can prove that Minco built a coherent plan. It cannot prove that the process starts, the database opens, migrations apply, or the HTTP boundary responds.

4. Start and exercise the application

cargo minco dev --profile sqlite

In another terminal, exercise the health contract:

curl --fail --silent http://127.0.0.1:3000/health/live
curl --fail --silent http://127.0.0.1:3000/health/ready

The liveness response follows the generated contract and includes whether the process is live plus the generated service name. Readiness evaluates selected dependencies without exposing provider credentials or internal diagnostics.

Ctrl-C stops the supervised process group. It does not silently reset durable data.

5. Understand the ownership boundaries

Layer	Owns	Must not own
Contract	Client-visible operations, schemas, examples, security, and public failures	SQL, provider clients, or business implementation
Domain	Invariants and state transitions	Axum extractors, SQLx queries, or AWS types
Application	One use case, authorization, transaction intent, and owned ports	Provider-specific persistence or transport mapping
Adapter	SQLite, PostgreSQL, DynamoDB, or provider implementation details	Business policy that should be portable
HTTP	Extraction, validation mapping, one use-case call, and response mapping	Database queries or hidden orchestration
Evidence	What was checked, exercised, packaged, deployed, or observed	Claims stronger than the underlying proof

This separation is what lets the same use case run behind a local Axum service or a native Lambda HTTP runtime without moving business rules into the transport.

6. Add a resource deliberately

Preview the generated vertical slice before writing files:

cargo minco make resource widget --dry-run --json

Then follow the required order:

1. Define the client boundary.

   Add OpenAPI requests, responses, security, examples, idempotency, pagination, conditional mutation, and Problem bodies.

2. Synchronize deterministic bindings.

   Review generated changes instead of hand-maintaining a second schema model.

3. Write the nearest failing test.

   Start with a pure domain test or an application test using fake ports.

4. Implement one use case.

   Keep authorization and business decisions in the application boundary.

5. Add persistence only when needed.

   Implement the application-owned port with SQLite first, then add another adapter for a justified production access pattern.

6. Exercise the real HTTP boundary.

   Use an in-process Axum router so extraction, headers, status codes, and Problem mapping are covered together.

7. Inspect operational consequences.

   Review resources, IAM, connection pressure, cost classes, wake sources, and evidence before selecting an AWS profile.

The resource API guide supplies standard create, list, read, update, and delete shapes without introducing a generic repository or ORM.

7. Run the local gates

cargo minco test unit
cargo minco test feature
cargo minco check --with-cargo

Local success is not deployment proof. Packaging, hosted CI, provider-backed verification, promotion, and production observation remain separate evidence.

8. Compare with a complete application

The first project proves the development loop. The Orders API end-to-end recipe adds idempotent create, opaque cursor pagination, strong ETags, conditional updates and deletes, real persistence adapters, and release planning. The production blueprint then explains how traffic, failure behavior, wake sources, residual cost, and recovery affect the runtime choice.

Continue with the framework tour, the feature catalog, or the Orders recipe.