Skip to main content

Best Practices

This is the recommended operating model for W7S apps if you want the repo to stay easy for both humans and agents.

Repository shape​

Use a predictable layout:

backend/
  src/
frontend/
  dist/
db/
  app/
    migrations/
w7s.json
w7s.site.json

If the app is backend-only, a root src/ layout is acceptable for small examples. For larger apps, prefer backend/src.

Routes​

  • keep route declarations in w7s.json
  • use one handler per file
  • keep paths stable and explicit
  • use auth: none only when the route is intentionally public

Database​

  • use SQL only for migrations
  • use Drizzle schema and query builder in runtime code
  • create one shared DB client module with createW7SDbClient
  • do not scatter handwritten SQL strings through handlers

Frontend​

  • publish only built assets in frontend/dist
  • keep frontend source and build tooling separate from deploy output
  • use scope=frontend deploy workflows when frontend changes independently

Deploy workflows​

  • use repo-scoped deploy endpoints: /<repo>/_deploy
  • prefer artifact=prebuilt when CI already built the runtime handlers
  • use scope=backend or scope=frontend when the repo contains both
  • run typecheck before deploy
  • print deploy response body on failure

Handlers​

  • keep responses structured and deterministic
  • avoid noisy debug logs in example handlers
  • expose a /health route with deploy metadata
  • keep handler files short and move reusable logic into shared modules

SDK usage​

  • use @w7s-io/sdk for local scripts and smoke tests
  • set W7S_ORG_URL, W7S_REPO, and GITHUB_TOKEN explicitly
  • use the same SDK DB client locally and in runtime when possible

Docs​

  • keep services/*/DOCS.md and plugins/*/DOCS.md current
  • treat docs as part of the product surface
  • update examples when platform conventions change

Good default philosophy​

Optimize for:

  • one obvious repo layout
  • one obvious DB client
  • one obvious deploy workflow per concern
  • one obvious place to learn the platform

That reduces ambiguity, which is the main thing that slows agents down.