Decision Graph

The .trurlic/ directory is the on-disk representation of your architecture. It is meant to be committed to git — it is your architecture’s source of truth.

File layout

.trurlic/
  project.toml                    Project metadata and format version
  graph.toml                      Compiled edge index (derived, rebuildable)
  components/
    auth.toml                     Component definition
    database.toml
    rate-limiter.toml
  decisions/
    auth-jwt-with-dpop-binding.toml
    database-postgresql-15.toml
    rate-limiter-redis-sliding-window.toml
  patterns/
    state-in-redis.toml
  .state/                         Session data (gitignored, not versioned)
    sessions/                     Design session persistence
    tmp/                          Temporary files for atomic writes

Project metadata

trurlic_version = "0.1.0"

[project]
name = "my-project"
description = "A brief description of the project"

Component schema

[component]
name = "auth"
description = "Authentication and token management"

Component names must be valid kebab-case. The filename must match the name field.

Decision schema

[decision]
component = "auth"
choice = "JWT with DPoP binding"
reason = "Stateless, no session store needed"
alternatives = [
  "Session cookies — rejected: requires server-side state",
  "Opaque tokens — rejected: requires a token introspection endpoint"
]
tags = ["security", "authentication"]
attribution = "user"
created = 2025-06-10T14:30:00Z

Project-wide decisions (rules) use component = "project". These appear in every component’s context brief as inviolable constraints.

Decision fields

Field	Required	Description
`component`	Yes	Owning component name, or `"project"` for rules
`choice`	Yes	Concise decision title
`reason`	Yes	Reasoning behind the decision
`alternatives`	No	Rejected options with reasons
`tags`	No	Categorical tags for filtering and search
`attribution`	Yes	`"user"` (human authored) or `"agent"` (autonomous)
`created`	Yes	UTC timestamp in RFC 3339 format

Pattern schema

[pattern]
name = "state-in-redis"
description = "Shared Redis pool via app state, no per-component connections"
decisions = ["auth-jwt-with-dpop-binding", "rate-limiter-redis-sliding-window"]
components = ["auth", "rate-limiter"]
tags = ["infrastructure", "state"]

Patterns require at least two source decisions. Components are inferred from decisions if omitted.

Graph index

graph.toml is a compiled edge index — a derived file rebuilt deterministically from node files. It maps every node to its edges and stores BLAKE3 content hashes for integrity verification.

Do not hand-edit graph.toml. It is rebuilt on every write and on trurlic check --rebuild. Edit node files instead, then run trurlic check to reconcile.

Edge types

Edge	Meaning
`BelongsTo`	Decision → Component
`ConnectsTo`	Component → Component (directional data/control flow)
`DependsOn`	Decision → Decision (logical dependency)
`Constrains`	Decision → Decision (restriction)
`Supersedes`	Decision → Decision (replacement)

Git integration

.trurlic/ is designed for version control. Commit the entire directory — except .trurlic/.state/, which trurlic init adds to .gitignore automatically. The .state/ directory contains design session persistence data and temporary files that are local to each developer’s machine.

Merge conflicts in TOML files resolve naturally — if two branches add different decisions, both files appear after merge. Run trurlic check --rebuild after merging to reconcile the index.