Envia Admin

Appearance

Contributing to Documentation ​

This guide explains when, where, and how to document changes in the Envia Admin platform.

When to Document ​

Document whenever you complete a significant change:

  • A new business module or feature (e.g., billing, shipping rules)
  • A new group of API endpoints
  • A new reusable component or composable
  • A new architectural pattern or convention
  • An end-to-end project that touches both backend and frontend

Rule of Thumb

If another developer would need more than 5 minutes to understand what you built by reading only the code, it deserves documentation.

Where to Document ​

The documentation is organized into two dimensions: shared knowledge by layer and feature knowledge by module.

Decision Tree ​

What did you build?Where to document
Reusable UI componenttechnical/frontend/components/<name>.md
Reusable composabletechnical/frontend/composables/<name>.md
Backend pattern or conventiontechnical/backend/
Frontend pattern or conventiontechnical/frontend/
Business module or featuretechnical/modules/<module-name>/
User-facing workflowguide/modules/<module-name>.md
New API endpoints (part of a module)technical/modules/<module-name>/api.md
New API endpoints (standalone)reference/api-endpoints.md

Understanding the Two Dimensions ​

Shared knowledge (HOW things work)     Feature knowledge (WHAT was built)
─────────────────────────────────      ─────────────────────────────────
technical/backend/                     technical/modules/billing/
  architecture.md                        index.md  (overview, data flow)
  api.md (conventions)                   api.md    (billing endpoints)
  database.md                            ui.md     (billing screens)

technical/frontend/                    technical/modules/shipping/
  architecture.md                        index.md
  components/                            api.md
  state.md                               ui.md
  • Shared knowledge answers: "How do we build things here?" (patterns, components, conventions)
  • Feature knowledge answers: "What does this module do and how does it work?" (business logic, endpoints, screens)

How to Document a New Module ​

Step 1: Create the module folder ​

bash
mkdir -p documentation/technical/modules/<module-name>

Step 2: Copy the template ​

bash
cp documentation/technical/modules/_template.md documentation/technical/modules/<module-name>/index.md

Step 3: Fill in the sections ​

Open the copied index.md and fill in each section. The template includes:

  • Overview — What the module does and why it exists
  • Data Flow — How data moves through the system
  • Database — Tables and relationships involved
  • Key Decisions — Design trade-offs and reasoning

Step 4: Add API documentation (if applicable) ​

Create api.md in the module folder with:

  • Endpoint table (method, path, description, auth)
  • Request/response examples
  • Module-specific error codes

Step 5: Add UI documentation (if applicable) ​

Create ui.md in the module folder with:

  • Main screens and their purpose
  • Module-specific components (if any)
  • User flows (happy path and edge cases)

Step 6: Add user guide (if applicable) ​

If the module has a user-facing interface, create guide/modules/<module-name>.md with step-by-step instructions for end users.

Step 7: Update the sidebar ​

Add your new pages to the sidebar configuration in .vitepress/config.mts:

typescript
// In the '/technical/' sidebar, under the Modules section:
{
  text: 'Your Module Name',
  collapsed: true,
  items: [
    { text: 'Overview', link: '/technical/modules/<module-name>/' },
    { text: 'API', link: '/technical/modules/<module-name>/api' },
    { text: 'UI', link: '/technical/modules/<module-name>/ui' },
  ],
},

Step 8: Verify ​

bash
cd documentation
npm run dev

Check that all links work and the sidebar renders correctly.

Writing Guidelines ​

  • Language: All documentation must be in English
  • Be concise: Favor tables and code examples over long paragraphs
  • Explain the "why": Document decisions and trade-offs, not just the "what"
  • Use diagrams: VitePress supports Mermaid diagrams natively for data flows
  • Keep it current: Update documentation when the code changes
  • Link, don't duplicate: Reference shared docs (components, patterns) instead of copying

File Naming Conventions ​

  • Use kebab-case for file and folder names: user-management/, api-endpoints.md
  • Module folders match the feature domain name: billing/, shipping/, user-management/
  • Use index.md as the entry point for any folder

Envia Admin