tutti/docs/conventions/tuttid-layering.md

Tuttid Layering

This document defines the internal layering rules for services/tuttid.

Purpose

tuttid is the primary business core for the open-source local product.

Its directory structure should follow a clear layered desktop-daemon model, while remaining scaled to the current size of tuttid.

Current Layout

services/tuttid/
  main.go
  wiring.go
  app/
  api/
  biz/
  data/
  integration/
  server/
  service/
  types/

Layer Responsibilities

main.go

Owns process bootstrap only:

• logger setup
• signal handling
• startup error handling
• calling into app

main.go should not contain domain logic or route wiring details.

wiring.go

Owns composition root responsibilities:

• open local backends
• run migrations
• construct services and handlers
• register route dependencies
• close long-lived resources on shutdown

wiring.go is allowed to know concrete implementations. Other layers should depend on interfaces or narrow collaborators whenever possible.

app/

Owns process lifecycle around the HTTP server:

• listen
• shutdown
• signal-aware termination

app/ should not grow domain-specific behavior.

server/

Owns HTTP server assembly:

• mux creation
• route registration entrypoint
• HTTP middleware such as CORS
• address selection helpers

server/ should not contain domain request handling logic.

api/

Owns transport-facing HTTP behavior:

• request decoding
• response encoding
• HTTP status selection
• path and method dispatch
• generated API-specific DTOs

Domain transport support should live under its domain package, for example:

• api/workspace/types.go

The api/ layer may depend on:

• service/
• domain-local DTOs
• shared helpers from types/

The api/ layer must not depend on concrete persistence details except for narrow sentinel error mapping where needed.

service/

Owns use-case orchestration:

• business workflow sequencing
• validation that belongs to domain behavior
• translating between domain models and API DTOs
• calling persistence and other configured collaborators

service/ should not perform direct SQL or HTTP response writing.

Agent service composition

The service/agent facade is constructed from one responsibility-grouped ServiceConfig. Production wiring must resolve canonical/runtime ports, provider preparation, query/projection, composer, import, resource, and observer dependencies before calling NewService; it must not fill Service fields or install an application Host afterward.

packages/agent/host remains the lifecycle owner. Its tuttid support ports are narrow components created from the completed config and must not retain the complete Service facade. A support component may share a lock, cache, runtime preparer, or observer registry with Service. Read-only canonical seams are allowed only when their lifecycle ownership is explicit; the Session Fork runtime-preparation seam reads lineage that can exist only after commit and never performs a lifecycle write.

biz/

Owns small, transport-agnostic domain models and domain rules that need to be shared across layers.

Use biz/ when:

• both service/ and data/ need the same domain object
• the type should not live in api/
• the type is still domain-local rather than global

Example:

• biz/workspace/model.go

Do not turn biz/ into a giant dumping ground. Keep it domain-scoped and intentionally small.

data/

Owns concrete persistence adapters:

• SQLite access
• migrations
• local file-backed repositories when they belong to persistence

data/ should depend on:

• biz/
• minimal shared helpers from types/

data/ must not depend on api/.

Within a domain adapter directory, prefer splitting by responsibility:

• store.go for interfaces and sentinel errors
• backend implementation files such as sqlite_store.go
• migrations.go for schema setup

integration/

Owns process-level and cross-layer black-box tests:

• starting a real tuttid process
• exercising real HTTP endpoints
• verifying durable state behavior through the public daemon surface
• covering startup, recovery, and other flows that cross api/, service/, and data/

Use integration/ when a test is no longer about one layer in isolation. Keep unit and near-layer tests next to the code they exercise; use integration/ only for daemon-wide behavior.

types/

Owns cross-domain support code only:

• HTTP helpers
• state path helpers
• truly shared primitives

Do not place domain-local request or response DTOs in types/.

Complexity Guidance

Directory and layering rules exist to clarify ownership, not to maximize file count.

When logic is still small, focused, and easy to understand, prefer the narrowest structure that keeps responsibility clear. Do not split code into multiple files or layers unless the split creates a clearer boundary.

Prefer keeping code together when:

• it still serves one responsibility
• there is only one implementation
• the control flow is easy to follow in one place
• testing and future changes are not being made harder by the current shape

Prefer splitting code when:

• one unit is carrying more than one responsibility
• transport, domain, and persistence concerns are starting to mix
• a separate interface is needed for multiple implementations
• the current file is becoming harder to understand than the boundary you would introduce
• readers need to jump across several thin files to understand one simple flow

Clear boundaries matter more than symmetric directory shapes.

Do not create a full domain slice until that domain has enough real behavior to justify it.

Examples:

• a simple health endpoint does not need a full runtime domain
• a small helper does not need its own package
• a domain does not need api/, biz/, service/, and data/ on day one if only one slice is real

Rule Of Thumb

When adding new logic, ask:

1. Is this a new responsibility, or just more code for the same responsibility?
2. If I keep this in the current file, does it become confusing?
3. If I split this out, does the new boundary make the code easier to understand, test, or replace?

If the answer to 2 and 3 is "not really", keep it together for now.

Dependency Direction

Preferred dependency flow:

main
  -> wiring
    -> app
    -> server
    -> api
      -> service
        -> biz
        -> data
          -> biz
    -> types

Practical rules:

• api can depend on service
• service can depend on biz and data
• data can depend on biz
• data must not depend on api
• biz must not depend on api, service, or data

Test Placement

Prefer placing tests according to the responsibility they validate:

• keep unit and near-layer tests beside the owning package with *_test.go
• keep process-level and cross-layer daemon tests under integration/
• use testdata/ only for fixtures and sample data, not for test logic

Examples:

• api/daemon_test.go for generated daemon adapter behavior
• data/workspace/sqlite_store_test.go for persistence behavior
• integration/blackbox_test.go for real-process daemon regression coverage

When To Add A New Domain

Create a full domain slice only when a domain has enough real behavior to justify its own boundary.

When a new domain such as runtime or agent is introduced, follow the same structure:

api/runtime/
biz/runtime/
data/runtime/
service/runtime/

Create only the slices that are justified by actual use. Do not pre-create deep empty trees.

Review Rules

When reviewing tuttid changes, ask:

1. Does this code belong to a transport layer, business layer, or persistence layer?
2. Is a domain-local DTO being pushed into global types/?
3. Is data/ accidentally depending on api/?
4. Is wiring.go staying as composition root instead of becoming a second service layer?
5. Are empty directories being introduced before they have real ownership?