build-scala-service

Build Scala Service

Purpose

Implement Scala backend behavior with Scala as a first-class JVM path.

The practical decision is how to use immutable data, explicit effects or futures, clear module boundaries, and focused tests without translating Java service patterns into Scala syntax.

When To Use

• Use this skill when the repository is Scala-first and the task changes backend behavior.
• Use this skill when the user asks for functional JVM backend work and repo context does not point elsewhere.
• Use this skill when choose-service-shape routes implementation to Scala.
• Use Java guidance instead for Java-dominant backend modules, and Android guidance for Android app/platform work.

Source Check

Use repo-local JVM files, checked-out dependency sources, Dash MCP or Dash HTTP for installed JVM docsets, and then official or canonical documentation when Dash/local coverage is missing or stale:

• Scala documentation
• Scala 3 Book
• SBT Reference Manual
• ScalaTest User Guide
• MUnit documentation

Use framework documentation for framework-specific behavior. Translate documentation rules into concrete code, test, or validation decisions.

Implementation Workflow

1. Inspect the existing Scala shape:
   • Scala version
   • SBT, Gradle, or Maven project layout
   • package and module names
   • framework entry points
   • effect model, future model, or synchronous style
   • test framework
   • formatting and lint expectations
2. Model data functionally:
   • prefer immutable case classes for product data
   • use sealed traits or enums for closed alternatives
   • use Option for expected absence
   • use Either, validated values, or the repo's effect error channel for recoverable domain errors
   • avoid null unless interoperating with Java or a framework API that requires it
3. Keep behavior composable:
   • write small pure functions for domain transformations where practical
   • keep routing, request decoding, and response encoding at the edge
   • pass dependencies explicitly through the repository's existing pattern
   • avoid abstracting with typeclasses unless the abstraction has more than one real use or matches local style
4. Preserve the async/effect model:
   • use Future if the project is Future-based
   • use the repository's established effect system when one exists
   • do not introduce Cats Effect, ZIO, Akka/Pekko, or another runtime for one feature
   • keep resource acquisition, cancellation, retries, and timeouts explicit around external dependencies
5. Add focused tests:
   • test pure domain behavior directly
   • add route or integration tests when serialization, auth, persistence, or framework behavior changed
   • preserve ScalaTest, MUnit, Weaver, or repository-selected style

Framework Boundaries

Preserve the existing framework unless the user asks for a framework decision.

• Keep http4s, ZIO HTTP, Akka/Pekko, Play, Spring, or framework-specific code at the service edge.
• Keep domain and validation code framework-light when it will be reused or tested independently.
• Do not make one framework's module structure the default for another framework.

Validation

Use server-side-jvm:build-tooling-workflow to choose exact commands.

Common validation shapes:

• SBT module: sbt module/test
• SBT full check: sbt test
• Gradle Scala module: ./gradlew :module:test
• Maven Scala module: mvn -pl module -am test

Run broader validation before commit, push, PR, release, or cross-module behavior changes.

Output Shape

Return:

1. Changed behavior: the Scala service behavior or API changed.
2. Functional boundary: pure domain, effectful service, route edge, persistence adapter, config, or test.
3. Data model: case classes, sealed traits/enums, options, eithers, validated values, or existing convention.
4. Effect model: synchronous, Future, Cats Effect, ZIO, Akka/Pekko, or existing runtime.
5. Validation: exact build and test commands and results.

Guardrails

• Do not treat Scala as Java with different syntax.
• Do not introduce an effect system, framework, or typeclass abstraction without a real project reason.
• Do not use null or exceptions for ordinary domain flow unless local conventions require it.
• Do not convert Java modules to Scala unless the user asks.
• Do not make Android app/platform concerns part of this skill.