Skip to content

docs: clarify durable application implementation patterns - #38

Open
cmilesio wants to merge 1 commit into
mainfrom
docs/agent-implementation-guidance
Open

docs: clarify durable application implementation patterns#38
cmilesio wants to merge 1 commit into
mainfrom
docs/agent-implementation-guidance

Conversation

@cmilesio

Copy link
Copy Markdown
Member

What

Clarify the application patterns that humans and coding agents need when moving beyond generated scaffolds:

  • show how make:model and .db-relationships.yaml work together, including generation order and repository ownership of joins and preloads;
  • prefer a named result struct when several values form one cohesive service result, while preserving conventional (value, error) returns;
  • explain when durable file categories deserve named storage instead of direct filesystem access;
  • show a controller translating a storage-backed image into explicit cache policy, ETag validation, and a bodyless 304 Not Modified response;
  • give React, Vue, and templ/HTMX concrete loading guidance that avoids fast-request flicker, retains usable content during revalidation, and still models intentional loading, error, empty, and ready states;
  • refresh the checked-in cache, upload, report-job, and report-schedule scenario pages from their authoritative GoForj specs so resource generation, ID-only job payloads, repository reloads, and schedule inputs match the executable workflows.

The frontend guidance deliberately avoids an absolute “load everything before rendering” rule. Required page data should be stable before the page presents itself as ready, while genuinely independent regions can still load progressively. Transient indicators are delayed; loaded data is never artificially delayed.

The executable evaluation scenarios and relationship behavior are tracked in GoForj PR #70, with agent guidance and semantic verifiers in Atlas PR #6.

Why

Generated scaffolds establish framework registration, but they do not teach every application-level decision. Without explicit guidance, agents tend to globalize feature data, flash loaders around sub-second requests, return growing tuples, navigate database relationships outside repositories, write durable files to incidental local directories, or serve unchanged media repeatedly.

These pages make the preferred boundaries concrete without turning them into rigid universal rules. The result is guidance that is easier for people to apply, easier for Atlas to retrieve, and aligned with the executable scenarios used to evaluate agent behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant