flowCreate.solutions

Documentation (Project Standard)

This section defines the Flow Create Solutions standard for project documentation.

These standards are meant to be:

  • Generic by design: reusable across many projects.
  • Consistent: predictable naming, structure, and expectations.
  • Practical: minimal required docs, with clear optional extensions.

What goes where (source of truth)

This standards site

This site is the source of truth for cross-project conventions, such as:

  • Architecture and module patterns
  • Security posture and controls
  • Database patterns and migrations policy
  • Testing philosophy and structure
  • Development conventions (logging, error handling)

Project repositories

Each project repository is the source of truth for project-specific facts, such as:

  • Exact versions, ports, and environment variables
  • How to run locally (the actual commands)
  • Production deployment details and operational reality
  • Project-specific architecture decisions and tradeoffs
  • Known incidents/failure modes and troubleshooting steps

Rule: When referencing cross-project conventions, project docs must include hyperlinks to the live Engineering Standards site: https://docs.flowcreate.solutions/.

Avoid linking to repo file paths (e.g., docs/backend/...) in project docs—projects should link to the published standards website so references remain stable and accessible.

General rules

  • Docs live with the code: major modules (e.g. backend, frontend) must have a centralized docs/ folder.
  • Every docs/ has an index.md: it must be a curated entry point, not a dumping ground.
  • Docs change with behavior: if a PR changes how to run, debug, operate, or integrate, update the relevant docs in the same PR.
  • Keep docs copy/pasteable: commands should work (or be clearly marked as placeholders).
  • Avoid duplicating standards: prefer hyperlinks to https://docs.flowcreate.solutions/ for anything “how we do things across projects”.
  • Project documentation structure: docs/documentation/project_structure.md
  • ADR standard: docs/documentation/adr.md
  • Runbooks / operations docs: docs/documentation/runbooks.md
  • Templates: docs/documentation/templates.md