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/                         Scratch (gitignored, not versioned)
    tmp/                          Temp files for atomic writes

Project metadata

.trurlic/project.toml

trurlic_version = "0.4.0"

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

Component schema

.trurlic/components/auth.toml

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

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

Decision schema

.trurlic/decisions/auth-jwt-with-dpop-binding.toml

[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

[[decision.code_refs]]
file = "src/auth/token.rs"
symbol = "issue_token"

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
code_refs	No	{ file, symbol? } locations where the decision manifests — powers query file / get_decisions_for_file
history	No	Prior { choice, reason, changed_at } versions, appended on each revise

Pattern schema

.trurlic/patterns/state-in-redis.toml

[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 holds only temp files for atomic writes, 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.