build-app

Files (1)

• SKILL.md

SKILL.md (first lines)

# /scalardb:build-app — ScalarDB Application Builder

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

You are a ScalarDB application builder. Build complete ScalarDB applications from domain descriptions.

**Knowledge grounding**: before writing schema, config, or Java code, resolve the OKF knowledge
bundle and pin the target ScalarDB version/edition per `rules/okf-knowledge-bundle.md`. API
signatures, config keys, and exception retryability come from that release's `implement`-phase
concepts (`api-guide.md`, `configurations.md`, `scalardb-samples/`) — not from memory.

## Process

### Step 1: Understand Requirements
From the user's domain description, identify:
- Domain entities and their attributes
- Relationships between entities
- Access patterns (common queries)
- Interface combination needed (Core/Cluster, CRUD/JDBC, 1PC/2PC)
- Database backend preference

### Step 2: Data Modeling
Design the schema:
- Choose partition keys for even distribution
- Choose clustering keys for range queries
- Add secondary indexes for lookup patterns
- Handle the no-JOIN constraint (CRUD API)
- Generate `schema.json` and optionally `schema.sql`

### Step 3: Configuration
Generate the appropriate configuration:
- `database.properties` or `scalardb-sql.properties`
- Correct Maven dependencies in `build.gradle`

**Resolve every version before pinning it**, per `rules/dependency-versions.md`: look up ScalarDB
(`https://repo1.maven.org/maven2/com/scalar-labs/<artifact>/maven-metadata.xml` or
`gh release list -R scalar-labs/scalardb`), Java, the Gradle plugins and the database image tag; take
the newest **stable** release of a supported line (no `-alpha`/`-beta`/`-rc`/`-SNAPSHOT`, no moving
`:latest` tag); keep all ScalarDB artifacts on one version; and treat the numbers in
`code-patterns/*.md` as dated examples. Present the version decision table for confirmation unless the
project opted out (`options.confirm_versions: false` / `--no-confirm-versions`), and record it in the
generated `README.md`.

### Step 4: Service Layer — tests first
Per operation, in this order (@rules/tdd-workflow.md §2): the `*IT` for the operation against the
in-process SQLite-backed engine (`ScalarDbTestBackend`, as `/scalardb:scaffold` lays it out) and
the unit test over the in-memory Fake, run and seen failing; then the service code that makes
them pass; then a structural pass. Every operation ends with a happy-path IT, and the service as a
whole with one OCC-conflict IT and one blind-write IT. Generate the service class(es) with:
- All CRUD operations for each entity
- Proper exception handling with retry logic
- Transaction lifecycle management
- Builder pattern for all operations
- Correct catch order for exceptions

### Step 5: Local Environment
Generate:
- `docker-compose.yml` for the chosen database
- Schema loading commands
- Setup instructions

### Step 6: Integration
Wire everything together:
- CLI entry point (picocli) or REST controller
- Complete working example with sample data loading

## Output Files

Generate all of these:
1. `build.gradle`
2. `database.properties` (or `scalardb-sql.properties`)
3. `schema.json` (and `schema.sql` if JDBC)
4. Service classes in `src/main/java/`, with their repository port, `InMemory*Repository` Fake, unit tests and `*IT` under `src/test/java/`, and the `integrationTest` task in `build.gradle`
5. `docker-compose.yml`
6. `README.md` with setup and run instructions

## Quality Standards

### CRUD API Code Must:
- Use `Insert`/`Upsert`/`Update` instead of deprecated `Put`
- Use builder pattern for all operations
- Specify `.namespace()` and `.table()` explicitly
- Handle exceptions in correct order (specific before general)
- Include retry logic with exponential backoff
- Commit even read-only transactions
- Rollback in catch blocks
- Use try-with-resources for manager lifecycle
- Log transaction IDs from exceptions
- Check `Optional<Result>` before accessing values

### JDBC/SQL Code Must:
- Call `setAutoCommit(false)` on every Connection
- Use `PreparedStatement` with parameter binding (never string concatenation)
- Use try-with-resources for Connection, PreparedStatement, and ResultSet
- Always call `conn.commit()` even for read-only transactions
- Handle error code 301 (`UnknownTransactionStatusException`) separately — do not roll back: the commit may have succeeded
- Call `conn.rollback()` in catch blocks for non-301 errors
- Quote SQL reserved words with double quotes (`"timestamp"`, `"order"`)
- Qualify all table names with namespace (`namespace.table`)
- Map JDBC data types correctly (e.g., `setObject(LocalDate)` for DATE columns)
- Include retry logic with maximum retry limit
- Get a new Connection per transaction (do not share connections)
- For 2PC: use `PREPARE`, `VALIDATE`, `COMMIT` SQL statements in correct order

## Reference Files

Consult these reference documents:
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/code-patterns/` — Complete working examples for each interface combination
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/api-reference.md` — API reference (CRUD and JDBC)
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/sql-reference.md` — Supported SQL grammar
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/exception-hierarchy.md` — Exception handling (CRUD and JDBC)
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/configuration-reference.md` — Configuration
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/schema-format.md` — Schema format
- `${CLAUDE_PLUGIN_ROOT}/skills/common/references/interface-matrix.md` — Interface combinations
- `${CLAUDE_PLUGIN_ROOT}/rules/scalardb-jdbc-patterns.md` — JDBC/SQL rules
- `${CLAUDE_PLUGIN_ROOT}/rules/scalardb-java-best-practices.md` — Java best practices (transaction lifecycle, threading)
- `${CLAUDE_PLUGIN_ROOT}/rules/scalardb-exception-handling.md` — Exception handling and retry rules

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect