> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canton.network/llms.txt
> Use this file to discover all available pages before exploring further.

# cn-quickstart

> A full-stack reference application for building on Canton Network, with Daml contracts, Java backend, React frontend, and LocalNet.

The [cn-quickstart](https://github.com/digital-asset/cn-quickstart) repository is a complete example application that demonstrates how to build, test, and run a Canton Network application. It includes Daml smart contracts, a Java backend, a React frontend, and a LocalNet environment for local development.

## Repository Overview

Clone the repository:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/digital-asset/cn-quickstart
cd cn-quickstart
direnv allow
cd quickstart
```

The repository uses Nix and Direnv for reproducible development dependencies. If you prefer not to use Nix, work directly in the `quickstart/` directory and manage dependencies (JDK, Node.js, dpm) manually.

## Project Structure

```
cn-quickstart/
  .envrc                    # Nix/Direnv activation
  nix/                      # Nix development dependencies
  quickstart/
    Makefile                # Build and run commands
    compose.yaml            # Docker Compose configuration
    .env                    # Environment variables
    daml/                   # Daml smart contracts
      Licensing/
        AppInstall.daml     # User onboarding workflow
        License.daml        # License management
        Util.daml           # Helper functions
      dars/                 # Splice DAR dependencies
    backend/                # Java Spring Boot backend
      src/main/java/...
        ledger/             # Ledger API client
        repository/         # PQS queries
        pqs/                # SQL generation
        service/            # REST endpoints
        security/           # OAuth2 auth
    frontend/               # React TypeScript frontend
      src/
        components/         # UI components
        api/                # Generated API client
    common/
      openapi.yaml          # Shared API definition
    docker/                 # Docker image definitions
      modules/
        localnet/           # LocalNet configuration
    config/                 # Service configuration files
```

## The Reference Application

cn-quickstart implements a software licensing workflow with four parties:

* **App Provider** -- Creates and sells licenses
* **App User** -- Purchases and holds licenses
* **Super Validator (SV)** -- Operates the payment infrastructure
* **DSO Party** -- The decentralized synchronizer operator for Canton Coin

The Provider and User each run on their own validator. License purchases involve Canton Coin payments processed through the Splice wallet system.

## Running the Application

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
cd quickstart
make install-daml-sdk    # Install the Daml SDK
make setup               # Select deployment profile
make build               # Compile contracts, backend, frontend
make start               # Launch LocalNet and all services
```

Once running, the frontend is accessible in your browser. See the [QuickStart walkthrough](/appdev/quickstart/running-the-demo) for a step-by-step guide.

## Extending the Example

### Adding Your Own Templates

Create new `.daml` files in the `daml/` directory. After writing your templates:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dpm build                # Compile
dpm test                 # Run tests
make build               # Rebuild everything including codegen
make restart             # Restart services
```

The build system regenerates Java bindings from the updated DAR file, so your backend can reference the new templates immediately.

### Modifying the Backend

The backend follows a standard Spring Boot layout. To add a new endpoint:

1. Define the endpoint in `common/openapi.yaml`
2. Add the service implementation in `backend/src/main/java/.../service/`
3. Add PQS queries in `repository/` if you need to read contract data
4. Add Ledger API commands in `ledger/` if you need to submit transactions
5. Rebuild with `make build-backend`

### Custom Frontend

The React frontend consumes the backend's REST API. To modify it:

1. Update or add components in `frontend/src/components/`
2. Regenerate the API client if you changed `openapi.yaml`
3. Rebuild with `make build-frontend`

The frontend never interacts with the Ledger API directly -- all ledger access goes through the backend.

### Switching Architectures

cn-quickstart uses a fully mediated architecture (backend handles all ledger access). You can switch to a CQRS pattern where the frontend submits commands directly to the Ledger API using TypeScript bindings generated by `dpm codegen-js`. See [SDKs and APIs](/appdev/modules/m4-sdks-apis) for a comparison of both approaches.

## Related Pages

* [QuickStart walkthrough](/appdev/quickstart/running-the-demo) -- Step-by-step guide to running the demo
* [Project structure](/appdev/quickstart/project-structure) -- Detailed breakdown of every directory and file
* [LocalNet](/sdks-tools/development-tools/localnet) -- The Docker Compose environment powering local development
* [Backend development](/appdev/modules/m4-backend-dev) -- Patterns from the cn-quickstart backend