Module Documentation Blueprint

Every satellite module in the VENI-AI platform must follow this standardized documentation schema. This ensures consistency for product owners, developers, and stakeholders.

---

📋 The Documentation Schema

A complete module specification consists of four key sections:

1. Overview (index.md)

High-level business context and value proposition.

• Problem Statement: What fragmentation is this module solving?
• Core Value: How does it benefit the organization?
• Shell Integration: Which Shell features does it inherit?

2. Specification (specification.md)

The "source of truth" for functional behavior.

• User Personas: Who uses this module and why?
• Feature List: Categorized list of capabilities with acceptance criteria.
• Business Rules: Constraints, limits, and edge cases.

3. Visuals & Mockups

Integrated into either the Overview or Specification.

• User Journey: How the user navigates the module.
• Mockups: High-fidelity CSS frames showing the UI inside the Shell.

4. Technical Reference

Detailed implementation details for engineers.

• Database Schema: ERDs and column definitions using Drizzle types.
• API Spec: REST and gRPC endpoint definitions with request/response examples.
• RBAC Matrix: Mapping of roles to specific permissions.

---

🛠️ Markdown Template

You can copy this template when starting a new module.

# [Module Name]

## 1. Overview
Describe the module's purpose. Mention its role as an **SCS** (Self-Contained System).

## 2. Key Features
- **[Feature 1]**: Acceptance criteria and business logic.
- **[Feature 2]**: Acceptance criteria and business logic.

## 3. Mockups
<div class="spec-frame">
  <!-- CSS Mockup Code Here -->
</div>

## 4. Technical Reference

### Database Schema
| Table | Columns | Description |
|:---|:---|:---|
| `table_name` | `id`, `org_id`, ... | Purpose of the table |

### API Endpoints
<span class="method get">GET</span> `/api/[resource]` — List items.
<span class="method post">POST</span> `/api/[resource]` — Create item.

### RBAC Matrix
| Permission | Resource | Action | Default Roles |
|:---|:---|:---|:---|
| View Items | `items` | `read` | All users |

---

Blueprint in Action

To see this schema applied to a real module, refer to the Drive Module documentation.