Project Documentation Structure

This document defines the standard documentation structure for Flow Create Solutions projects.

It supports both:

• Multi-repo: backend and frontend live in separate repositories.
• Monorepo: multiple modules live in one repository (e.g., backend/, frontend/, infra/).

Non-negotiables

• Every major module has a docs/ folder.
• Every docs/ folder has an index.md that acts as a curated entry point.
• Project docs do not duplicate standards: link to the centralized standards site for cross-project conventions.

Multi-repo structure (each repo is a module)

Use this when backend and frontend are separate repos.

Required

repo/
  README.md
  docs/
    index.md
    overview.md
    local_setup.md
    architecture.md
    operations.md
    troubleshooting.md

• README.md
  • What is this repo/module?
  • How to run locally (one “happy path” command)
  • Link to docs/index.md
  • Links to relevant standards pages (don’t restate conventions)
• docs/index.md
  • The “home page” for this module’s documentation
  • Short module description and quick links
  • Points to project-specific truth (ports, env vars, commands)
• docs/overview.md
  • Scope and responsibilities
  • Key workflows and constraints
  • Links to standards for conventions
• docs/local_setup.md
  • Exact steps for this repo (versions/ports/commands/env vars)
  • Must reference .env.example (or equivalent) when applicable
• docs/architecture.md
  • High-level diagram and key boundaries
  • Links to standards architecture/conventions where applicable
• docs/operations.md
  • Deploy notes, health checks, alerts, rollback guidance (project-specific)
• docs/troubleshooting.md
  • Common symptoms → likely causes → actions

Recommended (when applicable)

docs/
  api.md
  security.md
  testing.md
  decisions/
    YYYYMMDD_short_title.md

• docs/api.md: API usage notes; link to OpenAPI/Swagger where available.
• docs/security.md: project-specific threats/mitigations; link to standards security docs for baseline controls.
• docs/testing.md: how to run tests in this repo; link to standards testing philosophy for structure.
• docs/decisions/: ADRs for decisions that should persist beyond a PR description.

Monorepo structure (multiple modules in one repo)

Use this when the repository contains multiple major modules like /backend, /frontend, /infra.

Required (system-level + per-module)

repo/
  README.md
  docs/
    index.md
  backend/
    docs/
      index.md
      overview.md
      local_setup.md
      architecture.md
      operations.md
      troubleshooting.md
  frontend/
    docs/
      index.md
      overview.md
      local_setup.md
      architecture.md
      operations.md
      troubleshooting.md

• README.md (repo-level)
  • What is this system?
  • Which modules exist and where their docs live
  • A single “happy path” local run (or a short menu of 2–3 commands)
  • Link to docs/index.md and each module docs entrypoint
• docs/index.md (system home)
  • System overview + module map
  • Links to each module docs home
  • Pointers to standards for conventions
• <module>/docs/* (module specifics)
  • Same required pages as the multi-repo standard

Recommended (system-level)

docs/
  architecture.md
  operations.md
  decisions/
    YYYYMMDD_short_title.md

• docs/architecture.md: cross-module topology (only what’s needed; keep it high level).
• docs/operations.md: system-level runbooks (deploy, rollback, incidents).
• docs/decisions/: system-level ADRs.

How to link to standards (avoid duplication)

When project docs need to reference how we do something as a company, link to the live Engineering Standards website rather than duplicating content:

• https://docs.flowcreate.solutions/

Examples (website links):

• Security overview: https://docs.flowcreate.solutions/backend/security/overview/
• Database module structure: https://docs.flowcreate.solutions/backend/database/module-structure/
• Testing structure: https://docs.flowcreate.solutions/backend/testing/structure/
• Migrations policy: https://docs.flowcreate.solutions/backend/database/migrations/

Project docs should instead contain:

• Exact environment variable names and example values (never secrets)
• The local run command(s) that actually work
• The ports used in dev and where they’re configured
• How to deploy and roll back this specific system
• Known failure modes and real troubleshooting steps