Life Architecture

Product narrative: templ/prd.md. This document is the Flowbot implementation contract.

1. Position in Flowbot

Layer 3 — Business Logic
├── internal/modules/life/   # Use-case orchestration, seeds, lore outbox consumer
├── pkg/life/                # Pure formulas (cascade, loot, buffs)
└── pkg/capability/life/     # LLM quest evaluation and lore generation

Layer 2 — Capability
└── capability.Invoke(hub.CapLife, …) → LLM adapter

Layer 1 / 0 — Store + infra
└── life_* tables via LifeStore / ent; event_outbox for async lore

HTML UI lives in internal/modules/web under /service/web/life* (same pattern as hub/workflow pages).

2. Package map

internal/modules/life/          # Service, Bootstrap, outbox consumer, config
internal/modules/life/seed/     # embed JSON (equipment, loot tables)
internal/modules/fx.go          # Register()
pkg/life/                       # cascade, loot, buffs (no I/O)
pkg/capability/life/            # EvaluateQuest, GenerateInstanceLore
internal/store/ent/schema/      # life_*.go (int64 PK + string flag)
internal/store/life.go         # LifeStore facade (package store)
internal/store/postgres/        # only if methods are on Adapter (prefer LifeStore)
internal/modules/web/           # life_*_webservice.go; SetLifeService via life.OnService
pkg/views/pages|partials/       # life_*.templ
public/js/life-radar.js         # Character radar chart
public/js/life-stats.js         # Stats dashboard charts (Chart.js)
public/css/custom.css           # Life page styles (`.life-*`)

3. Identity model

• Platform users table is unchanged (account only).
• life_profiles is 1:1 with the signed-in web operator.
• life_profiles.user_id = web session UID from authenticateWeb / route.RequestContext.UID (string, e.g. user-admin).
• All domain rows FK to life_profile_id (int64), not platform user id.

4. Deviations from PRD

5. ER / tables

Reserved on inventory/slots: tarnished_until (nullable time). Lore: lore_status ∈ none | pending | ready | failed.

6. Service and capability API

LifeService (internal/modules/life):

Capability (hub.CapLife):

7. Bootstrap / seeds

• EnsureProfile: seed (and backfill) characteristics INT, PHY, WIL, CHA, CRE, FIN, WRI, FOC; class_type=Architect; empty equipped slots + AI context.
• Skills: GetOrCreate on evaluate/create (no default skill list).
• Bootstrap: idempotent upsert of equipment + loot tables + achievements from internal/modules/life/seed/*.json.

8. HTTP routes and User nav

Prefix: /service/web

Nav: Life module sidebar — Life, Stats, Quests, Skills, Inventory, Achievements, Rewards, Character.

9. Core flows and outbox contract

flowchart LR
  UserNav[UserNav] --> WebLife[web_life_handlers]
  WebLife --> LifeSvc[modules_life_Service]
  LifeSvc --> PkgLife[pkg_life]
  LifeSvc --> Store[LifeStore]
  LifeSvc --> CapLife[capability_life]
  CapLife --> LLM[chat_LLM]
  LifeSvc --> Outbox[event_outbox]
  Outbox --> LoreWorker[ProcessPendingLore]
  LoreWorker --> CapLife
  LoreWorker --> Store

Create quest

Web → CreateQuestFromPrompt → capability.Invoke(EvaluateQuest) → get-or-create skill → insert life_quests.

Complete quest

In one transaction:

1. Re-read profile pity; roll loot with pity; resolve drop equipment when needed.
2. Apply pkg/life cascade (skill → characteristic → profile) including pity write.
3. Mark quest completed.
4. Clear rust on equipped gear.
5. Maybe insert inventory + lore outbox (Boss, or difficulty SS/SSS).
6. Write life_action_logs.
7. Daily respawn clone when type is Daily.
8. Update achievement progress / unlocks.

HTMX returns immediate feedback (exp/gold/drop). Lore fills later. Completion-rate blend runs after commit.

Fail quest

In one transaction: mark quest Failed and set 24h tarnished_until on equipped slots + equipped inventory. Completion-rate blend runs after commit.

Outbox

• Event type string: life.inventory.lore_requested
• Payload: event_id, type, life_profile_id, inventory_id
• Consumer: modules/life ProcessPendingLore (poll unpublished outbox rows of this type)
• On success: set instance lore fields, lore_status=ready, mark outbox published
• On LLM / transient failure: leave outbox unpublished for retry; do not mark lore_status=failed
• On poison / malformed payload / malformed lore response / missing inventory: mark outbox published; if inventory is known and still pending, set lore_status=failed

10. Boundaries

• Modules must not import pkg/providers/*.
• Web handlers must not run ent queries; call LifeService only.
• Formulas only in pkg/life.
• Persistence: LifeStore in package store (internal/store/life.go; not a separate *_store.go package); schemas life_*.
• No JSON API under /service/life in v1.
• Web installs the domain service via life.OnService(web.SetLifeService) at module register time.
• Capability LLM failures use types.ErrProvider; web maps them to a generic toast (no raw LLM text).

11. Config

modules:
  - name: life
    enabled: true
    default_class: Architect

12. Testing notes

• pkg/life: table-driven unit tests (cascade, loot, pity, buffs, soft HP, blend).
• Module / web: package tests with fakes where needed.
• Cross-boundary BDD under tests/specs/life_spec_test.go (requires Docker).

13. Implementation status

Implemented in-tree: schemas (life_*), LifeStore, pkg/life, pkg/capability/life, internal/modules/life, web routes/UI, User nav, seed catalog, BDD specs.