DaraMex Docs

Appearance

Documentation Structure ​

DaraMex uses a Module-Centric documentation structure combined with standard cross-cutting directories. This structure is actively enforced by the documentation and daramex-docs AI agent skills.

Modular Hierarchy ​

All module-specific documentation resides in apps/docs/modules/<module-name>/. This grouping ensures that all context related to a single business domain (Identity, Infrastructure, etc.) is co-located.

Each module directory follows this standard structure:

  • index.md: The entry point and overview for the module.
  • features/: Documentation for specific user-facing or system-level features.
  • domain/: Business rules, entities, and invariant logic.
  • runbooks/: Operational guides, troubleshooting, and manual procedures.

Cross-Cutting Documentation ​

Architectural or project-wide documentation that spans multiple modules lives in standard top-level directories:

  • onboarding/: Guides for new developers joining the project.
  • product/: Product specifications, PRDs, and glossaries.
  • conventions/: Coding conventions (backend/ and frontend/).
  • security/: Security posture and guidelines.
  • operations/: Cross-cutting operational workflows and incident management.
  • architecture/: High-level system design and infrastructure overview.
  • adr/: Architecture Decision Records (ADRs).
  • workflows/: Engineering workflows (CI/CD, code styles).
  • templates/: Base templates for all document types.
  • legacy/: Superseded or archived documentation.

Guidelines for Adding Documentation ​

  1. Read the Registry First: Always check apps/docs/registry.md to see if a doc already exists for the topic.
  2. Identify the Location: Use the structure above to determine if the doc belongs in a specific module (modules/<module>/) or a cross-cutting folder.
  3. Use Frontmatter: Every document MUST contain standard frontmatter (title, summary, status, owner, last_reviewed, and optionally source_paths, replaces, replaced_by).
  4. Update the Registry: Add the new file to the appropriate section in apps/docs/registry.md.
  5. Update the Sidebar: Documentation is not auto-generated in the sidebar. You must manually add new pages to the routing object in apps/docs/.vitepress/config.ts.

Docs Tooling Notes ​

  • Browser-side dependencies used by VitePress plugins should be declared directly in apps/docs/package.json when the repo runs under pnpm's strict dependency resolution.
  • If a plugin pulls a CommonJS browser dependency that breaks during dev pre-bundling, prefer aliasing the bare import to an ESM entry in apps/docs/.vitepress/config.ts instead of patching generated cache files.

AI Agent Integration ​

This repository contains two .agents/skills that automate this workflow:

  • documentation: The generic core skill containing the templates and logical decision tree for where docs belong.
  • daramex-docs: The DaraMex-specific overlay that knows about our VitePress setup and registry.md file.

When using an AI agent (like Gemini CLI or GitHub Copilot), you can simply ask the agent to "Create a doc for X" and it will automatically invoke these skills to place the file in the correct folder, use the right template, and update the registry and VitePress config.