Project Standards

Project Standards

When to Apply

• After changing code, APIs, or architecture
• When adding or modifying features
• When the user asks to update docs or diagrams

Update Documentation and Diagrams Promptly

After any change that affects behavior, structure, or contracts:

• README: Update the root README and any README in the affected area (e.g. apps/*/README.md, packages/*/README.md, docs/**/README.md).
• Code/API changes: Update relevant API docs and any .puml diagrams under docs/ that describe the same area.
• Diagrams (English and Chinese): When updating diagrams, update both docs/en/ and docs/zh/ so they stay in sync (e.g. docs/en/rd/c4/, docs/zh/rd/c4/; docs/en/product/domain/, docs/zh/product/domain/; docs/en/rd/togaf/, docs/zh/rd/togaf/; docs/en/data/er-diagram/, docs/zh/data/er-diagram/).
• New modules or layers: Add or adjust C4/clean-architecture diagrams in both en and zh; keep layout in sync with code (e.g. clean-architecture-portfolio-api.puml).
• Data/DB changes: Update docs/en/data/er-diagram/ and docs/zh/data/er-diagram/ and any schema or data-architecture docs.

Do not leave docs or diagrams outdated; update them in the same change set when possible.

Seed Data When API Changes

When API or resources change (new or modified endpoints, schemas, or domain entities exposed as API):

1. Add or update seed data so local/demo can be restored with one command.
2. Use well-known, real-world data only. No placeholders like user1, test-xxx, or foo.

Numeric values (prices, quantities, rates) may be fictional; identifiers, names, and codes must follow the above style.

• Script: scripts/seed/generate-seed-data.js
• Method: Prefer POST /api/v1/<resource>/batch; legacy portfolio via POST /api/v1/seed.
• Run: From repo root pnpm run generate-seed-data (or via pnpm run start:server).

For new resources, add postBatch("/api/v1/<resource>/batch", [ ... ]) in seedResources() and update the final console.log resource count.

Checklist Before Finishing a Task

• README and other docs that describe the changed area are updated
• English and Chinese diagrams that describe the changed area are updated
• If API/resources changed: seed data added or updated in generate-seed-data.js using well-known data; no placeholder names; pnpm run generate-seed-data succeeds (with API running)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.