Initial commit
This commit is contained in:
Zhongwei Li
785
skills/ln-115-presentation-creator/SKILL.md
Normal file
785
skills/ln-115-presentation-creator/SKILL.md
Normal file
@@ -0,0 +1,785 @@
|
||||
---
|
||||
name: ln-115-presentation-creator
|
||||
description: Builds interactive HTML presentation with 6 tabs (Overview, Requirements, Architecture/C4, Tech Spec, Roadmap, Guides). Creates presentation/README.md hub. Worker under ln-110-documents-pipeline.
|
||||
---
|
||||
|
||||
# HTML Presentation Builder
|
||||
|
||||
This skill creates an interactive, self-contained HTML presentation from existing project documentation. It transforms Markdown documents into a professional, navigable web presentation with diagrams, collapsible sections, and modern UI.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**This skill is a WORKER** invoked by **ln-110-documents-pipeline** orchestrator OR used standalone.
|
||||
|
||||
Use this skill when:
|
||||
- Building HTML presentation from existing documentation
|
||||
- Rebuilding presentation after documentation updates
|
||||
- Creating standalone presentation for sharing (no full documentation setup needed)
|
||||
- Validating that source documentation is ready for presentation generation
|
||||
|
||||
**Part of workflow**: ln-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → ln-114-project-docs-creator → **ln-115-presentation-creator**
|
||||
|
||||
**Prerequisites**: Existing documentation in `docs/` directory with **required files**:
|
||||
- `docs/project/requirements.md` (REQUIRED)
|
||||
- `docs/project/architecture.md` (REQUIRED)
|
||||
- `docs/project/tech_stack.md` (REQUIRED)
|
||||
|
||||
**Optional files** (enhance presentation but not blocking):
|
||||
- `docs/project/api_spec.md`, `database_schema.md`, `design_guidelines.md`, `runbook.md`
|
||||
- `docs/reference/adrs/*.md` (ADRs with Category: Strategic|Technical)
|
||||
- `docs/reference/guides/*.md` (How-to guides)
|
||||
- `docs/tasks/kanban_board.md` (Epic Story Counters for Roadmap)
|
||||
|
||||
## How It Works
|
||||
|
||||
The skill follows a **7-phase workflow**: READ DOCS → VALIDATE SOURCE EXISTS → VALIDATE SOURCE QUALITY → CREATE DIR → COPY TEMPLATES → INJECT CONTENT → BUILD HTML.
|
||||
|
||||
**Phase 1: READ DOCS** - Load all project documentation from docs/
|
||||
**Phase 2: VALIDATE SOURCE EXISTS** - Check required files exist (requirements.md, architecture.md, tech_stack.md), warn if optional missing
|
||||
**Phase 3: VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (read-only validation)
|
||||
**Phase 4: CREATE DIR** - Create presentation/ directory + README.md navigation hub
|
||||
**Phase 5: COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/
|
||||
**Phase 6: INJECT CONTENT** - Parse MD docs → replace placeholders in tab files → delete example blocks
|
||||
**Phase 7: BUILD HTML** - Assemble modular components into standalone presentation_final.html
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Read Documentation
|
||||
|
||||
**Objective**: Load all project documentation for transformation.
|
||||
|
||||
**When to execute**: Always (first phase)
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Use docs/ as source**:
|
||||
- Read documentation from `docs/project/`, `docs/reference/`, `docs/tasks/` directories
|
||||
- Standard locations created by ln-114, ln-112, ln-113
|
||||
|
||||
2. **Read Core MD Documents**:
|
||||
- `project/requirements.md` - Functional Requirements
|
||||
- `project/architecture.md` - Architecture design, C4 diagrams
|
||||
- `project/tech_stack.md` - Technology versions, Docker configuration
|
||||
- `project/api_spec.md` - API endpoints, authentication (if exists)
|
||||
- `project/database_schema.md` - Database schema, ER diagrams (if exists)
|
||||
- `project/design_guidelines.md` - UI/UX design system (if exists)
|
||||
- `project/runbook.md` - Operational procedures (if exists)
|
||||
|
||||
3. **Read ADRs** (if exist):
|
||||
- `reference/adrs/adr-001-*.md` through `adr-NNN-*.md`
|
||||
- Parse ADR metadata (status, date, title, Category: Strategic|Technical)
|
||||
|
||||
4. **Read Guides** (if exist):
|
||||
- `reference/guides/*.md` - How-to guides for Guides tab
|
||||
|
||||
5. **Read Kanban Board** (if exists):
|
||||
- `tasks/kanban_board.md` - Epic Story Counters table for Roadmap progress
|
||||
|
||||
6. **Extract metadata**:
|
||||
- Project name, date, version from documents
|
||||
- Preserve Mermaid diagram blocks
|
||||
|
||||
**Output**: Loaded documentation data ready for validation and HTML generation
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Validate Source Documentation Exists
|
||||
|
||||
**Objective**: Verify that required source documentation exists before building presentation. Prevent building incomplete presentations.
|
||||
|
||||
**When to execute**: After Phase 1 (documentation loaded)
|
||||
|
||||
**Process**:
|
||||
|
||||
### 2.1 Check required files
|
||||
|
||||
**REQUIRED** (must exist - block execution if missing):
|
||||
- ✅ `docs/project/requirements.md`
|
||||
- ✅ `docs/project/architecture.md`
|
||||
- ✅ `docs/project/tech_stack.md`
|
||||
|
||||
For each required file:
|
||||
1. Use Glob tool: `pattern: "docs/project/{filename}"`
|
||||
2. If NOT found:
|
||||
- Add to missing list
|
||||
3. If found:
|
||||
- Check file size > 100 bytes (not empty)
|
||||
|
||||
**If ANY required file missing or empty:**
|
||||
```
|
||||
❌ ERROR: Cannot build presentation - missing required documentation:
|
||||
- docs/project/requirements.md [missing/empty]
|
||||
- docs/project/architecture.md [missing/empty]
|
||||
|
||||
Suggestion: Run ln-114-project-docs-creator to create missing files.
|
||||
|
||||
STOP execution.
|
||||
```
|
||||
|
||||
### 2.2 Check optional files
|
||||
|
||||
**OPTIONAL** (enhance presentation - warn if missing but continue):
|
||||
- ⚠️ `docs/project/api_spec.md` (for backend projects)
|
||||
- ⚠️ `docs/project/database_schema.md` (for projects with database)
|
||||
- ⚠️ `docs/project/design_guidelines.md` (for frontend projects)
|
||||
- ⚠️ `docs/project/runbook.md` (for operational projects)
|
||||
|
||||
For each optional file:
|
||||
1. Use Glob tool: `pattern: "docs/project/{filename}"`
|
||||
2. If NOT found:
|
||||
- Add to optional missing list
|
||||
|
||||
**If optional files missing:**
|
||||
```
|
||||
⚠ WARN: Optional files missing: [list]
|
||||
Presentation will have reduced content in some tabs.
|
||||
Continue execution.
|
||||
```
|
||||
|
||||
### 2.3 Check optional directories
|
||||
|
||||
**OPTIONAL directories:**
|
||||
- `docs/reference/adrs/` - check if any ADR files exist (`adrs/*.md`)
|
||||
- `docs/reference/guides/` - check if any guide files exist (`guides/*.md`)
|
||||
- `docs/tasks/kanban_board.md` - check for Roadmap data
|
||||
|
||||
For each directory:
|
||||
1. Use Glob tool to find files
|
||||
2. If empty/missing:
|
||||
- Log: `ℹ Optional directory empty: {directory} - related tab will show placeholder`
|
||||
|
||||
### 2.4 Report validation summary
|
||||
|
||||
Log summary:
|
||||
```
|
||||
✓ Source documentation validation completed:
|
||||
Required files:
|
||||
- ✅ requirements.md (found, 8.5 KB)
|
||||
- ✅ architecture.md (found, 15.2 KB)
|
||||
- ✅ tech_stack.md (found, 3.1 KB)
|
||||
Optional files:
|
||||
- ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content)
|
||||
- ✅ database_schema.md (found, 4.7 KB)
|
||||
- ⚠️ design_guidelines.md (missing)
|
||||
Optional directories:
|
||||
- ✅ adrs/ (5 ADR files found)
|
||||
- ⚠️ guides/ (empty - Guides tab will show placeholder)
|
||||
- ✅ kanban_board.md (found - Roadmap will show progress)
|
||||
```
|
||||
|
||||
**Output**: Validation passed (all required files exist) OR error (stop execution)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Validate Source Content Quality
|
||||
|
||||
**Objective**: Verify that source docs contain sufficient content for presentation generation. Warn about incomplete content but don't block execution.
|
||||
|
||||
**When to execute**: After Phase 2 (source files exist)
|
||||
|
||||
**Process**:
|
||||
|
||||
### 3.1 Check for Mermaid diagrams
|
||||
|
||||
**Required diagrams:**
|
||||
- `architecture.md` MUST have at least 1 Mermaid diagram (preferably C4 Context)
|
||||
- `database_schema.md` (if exists) MUST have ER diagram
|
||||
|
||||
For each file:
|
||||
1. Read file content
|
||||
2. Search for Mermaid code blocks: ` ```mermaid`
|
||||
3. Count diagrams
|
||||
|
||||
**If diagrams missing:**
|
||||
```
|
||||
⚠ WARN: Missing diagrams in architecture.md
|
||||
Expected: At least 1 Mermaid diagram (C4 Context, Container, or Component)
|
||||
Found: 0 diagrams
|
||||
|
||||
Presentation Architecture tab will have incomplete visualization.
|
||||
Suggestion: Add C4 diagrams to architecture.md before building.
|
||||
```
|
||||
|
||||
### 3.2 Check for placeholders
|
||||
|
||||
**Placeholder patterns to detect:**
|
||||
- `{{PLACEHOLDER}}` (template placeholder)
|
||||
- `[Add your ...]` (instruction placeholder)
|
||||
- `TODO:` (incomplete content marker)
|
||||
|
||||
For each source file:
|
||||
1. Read file content
|
||||
2. Search for placeholder patterns (case-insensitive)
|
||||
3. Collect matches with line numbers
|
||||
|
||||
**If placeholders found:**
|
||||
```
|
||||
⚠ WARN: Source docs contain placeholders:
|
||||
- requirements.md:42 - {{PROJECT_DESCRIPTION}}
|
||||
- tech_stack.md:15 - [Add your technology rationale]
|
||||
- api_spec.md:8 - TODO: Add authentication endpoints
|
||||
|
||||
Presentation will show incomplete content.
|
||||
Suggestion: Complete placeholders before building for professional result.
|
||||
```
|
||||
|
||||
### 3.3 Check content length
|
||||
|
||||
**Minimum expected lengths:**
|
||||
- `requirements.md` > 500 words
|
||||
- `architecture.md` > 1000 words
|
||||
- `tech_stack.md` > 200 words
|
||||
|
||||
For each file:
|
||||
1. Read file content
|
||||
2. Count words (split by whitespace, exclude code blocks)
|
||||
3. Compare to threshold
|
||||
|
||||
**If content too short:**
|
||||
```
|
||||
⚠ WARN: Sparse content detected:
|
||||
- requirements.md: 320 words (expected >500)
|
||||
- tech_stack.md: 150 words (expected >200)
|
||||
|
||||
Presentation may look incomplete with thin content.
|
||||
Suggestion: Expand documentation before building.
|
||||
```
|
||||
|
||||
### 3.4 Auto-fix opportunities
|
||||
|
||||
**None** - ln-115 is **read-only** for source docs:
|
||||
- ❌ Does NOT edit markdown documentation
|
||||
- ✅ Only READS and TRANSFORMS to HTML
|
||||
|
||||
**If issues found:**
|
||||
```
|
||||
💡 To fix content issues:
|
||||
- Run ln-114-project-docs-creator to complete documentation
|
||||
- Manually edit source files in docs/project/
|
||||
- Re-run ln-115-presentation-creator after fixes
|
||||
```
|
||||
|
||||
### 3.5 Report content quality summary
|
||||
|
||||
Log summary:
|
||||
```
|
||||
✓ Content quality validation completed:
|
||||
Diagrams:
|
||||
- ✅ architecture.md: 3 Mermaid diagrams found (C4 Context, Container, Component)
|
||||
- ⚠️ database_schema.md: No ER diagram found
|
||||
Placeholders:
|
||||
- ⚠️ Found 2 placeholders in 2 files (see details above)
|
||||
Content length:
|
||||
- ✅ requirements.md: 1,250 words
|
||||
- ✅ architecture.md: 2,100 words
|
||||
- ⚠️ tech_stack.md: 180 words (expected >200)
|
||||
|
||||
Warnings: 3 (non-blocking)
|
||||
Recommendation: Address warnings for professional result, or continue with current content.
|
||||
```
|
||||
|
||||
**Output**: Content quality report (warnings only, does not block execution)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Create Presentation Directory & README
|
||||
|
||||
**Objective**: Setup presentation directory structure and navigation hub.
|
||||
|
||||
**When to execute**: After Phase 3 (source validation complete, warnings logged)
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Create presentation directory**:
|
||||
```bash
|
||||
mkdir -p docs/presentation/
|
||||
```
|
||||
|
||||
2. **Check if presentation/README.md exists**:
|
||||
- Use Glob tool: `pattern: "docs/presentation/README.md"`
|
||||
- If file exists:
|
||||
- Skip creation
|
||||
- Log: `✓ docs/presentation/README.md already exists (preserved)`
|
||||
- Proceed to Phase 5
|
||||
- If NOT exists:
|
||||
- Continue to step 3
|
||||
|
||||
3. **Create presentation/README.md from template**:
|
||||
- Copy template: `references/presentation_readme_template.md` → `docs/presentation/README.md`
|
||||
- Replace placeholders:
|
||||
- `{{PROJECT_NAME}}` — from requirements.md
|
||||
- `{{LAST_UPDATED}}` — current date (YYYY-MM-DD)
|
||||
- Content structure:
|
||||
- **Purpose**: What is this presentation
|
||||
- **Quick Navigation**: Links to presentation_final.html and assets/
|
||||
- **Customization Guide**: How to edit source files in assets/
|
||||
- **Build Instructions**: How to rebuild after changes
|
||||
- **Maintenance**: When to rebuild, verification checklist
|
||||
|
||||
4. **Notify user**:
|
||||
- If created: `✓ Created docs/presentation/README.md (navigation hub)`
|
||||
- If skipped: `✓ docs/presentation/README.md already exists (preserved)`
|
||||
|
||||
**Output**: docs/presentation/README.md (created or existing)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Copy Templates to Project
|
||||
|
||||
**Objective**: Copy HTML/CSS/JS templates from skill references/ to presentation directory.
|
||||
|
||||
**When to execute**: After Phase 4 (presentation directory exists)
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Check if assets exist**:
|
||||
- Use Glob tool: `pattern: "docs/presentation/assets/"`
|
||||
- If `docs/presentation/assets/` exists:
|
||||
- Skip copying (user may have customized files)
|
||||
- Log: `✓ Presentation assets already exist - preserving user customizations`
|
||||
- Proceed to Phase 6
|
||||
- If NOT exists:
|
||||
- Continue to step 2
|
||||
|
||||
2. **Copy template files**:
|
||||
```bash
|
||||
cp references/presentation_template.html → docs/presentation/assets/
|
||||
cp references/styles.css → docs/presentation/assets/
|
||||
cp references/scripts.js → docs/presentation/assets/
|
||||
cp references/build-presentation.js → docs/presentation/assets/
|
||||
cp -r references/tabs/ → docs/presentation/assets/tabs/
|
||||
```
|
||||
|
||||
3. **Verify copied structure**:
|
||||
```
|
||||
docs/presentation/assets/
|
||||
├── presentation_template.html # Base HTML5 + 6 tab navigation
|
||||
├── styles.css # ~400-500 lines
|
||||
├── scripts.js # Tab switching + Mermaid init
|
||||
├── build-presentation.js # Node.js build script
|
||||
└── tabs/
|
||||
├── tab_overview.html # Landing page
|
||||
├── tab_requirements.html # FRs + ADRs
|
||||
├── tab_architecture.html # C4 diagrams
|
||||
├── tab_technical_spec.html # API + Data + Deployment
|
||||
├── tab_roadmap.html # Epic list
|
||||
└── tab_guides.html # How-to guides
|
||||
```
|
||||
|
||||
**Output**: Template files copied to docs/presentation/assets/ (or skipped if already exist)
|
||||
|
||||
**Note**: Templates contain placeholders (`{{VARIABLE_NAME}}`) that will be replaced in Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Content Injection & Example Cleanup
|
||||
|
||||
**Objective**: Parse MD documentation, inject into HTML templates, and remove example blocks to create project-specific presentation.
|
||||
|
||||
**When to execute**: After Phase 5 (templates exist in assets/)
|
||||
|
||||
**Process**:
|
||||
|
||||
### 6.1 Read and Parse MD Documents
|
||||
|
||||
Read and parse the following documentation files (from Phase 1):
|
||||
|
||||
1. **requirements.md**: Project name, tagline, business goal, functional requirements, constraints, success criteria
|
||||
2. **architecture.md**: Architecture diagrams (C4 Context/Container/Component), solution strategy, quality attributes
|
||||
3. **tech_stack.md**: Technology Stack table (with versions, rationale, ADR links), Docker configuration
|
||||
4. **api_spec.md** (if exists): API endpoints, authentication methods, error codes
|
||||
5. **database_schema.md** (if exists): ER diagrams, data dictionary (tables/columns/types)
|
||||
6. **design_guidelines.md** (if exists): Typography, colors, component library, accessibility
|
||||
7. **runbook.md** (if exists): Development setup, deployment procedures, troubleshooting
|
||||
8. **adrs/*.md**: All ADR files (parse title, status, category, content)
|
||||
9. **kanban_board.md** (if exists): Epic Story Counters table for Roadmap progress
|
||||
10. **guides/*.md** (if exist): How-to guides for Guides tab
|
||||
|
||||
### 6.2 Inject Content into Templates
|
||||
|
||||
Replace placeholders in copied template files with parsed content from project documentation.
|
||||
|
||||
**Key Placeholders (in tab templates):**
|
||||
|
||||
**Overview Tab** (`tab_overview.html`):
|
||||
- `{{PROJECT_SUMMARY}}` — Problem/Solution/Business Value structure (3 sections)
|
||||
- `{{TECH_STACK}}` — Technology badges (brief list only)
|
||||
- `{{STAKEHOLDERS}}` — Stakeholder cards with names and roles
|
||||
- `{{QUICK_FACTS}}` — Project Status, Total Epics, Deployment Model, Target Platforms
|
||||
- `{{NAVIGATION_GUIDE}}` — Documentation guide with tab descriptions
|
||||
|
||||
**Requirements Tab** (`tab_requirements.html`):
|
||||
- `{{FUNCTIONAL_REQUIREMENTS}}` — FRs table (ID, Priority, Requirement, Acceptance Criteria)
|
||||
- `{{ADR_STRATEGIC}}` — Strategic ADRs grouped section with accordion
|
||||
- `{{ADR_TECHNICAL}}` — Technical ADRs grouped section with accordion
|
||||
- `{{SUCCESS_CRITERIA}}` — Project success metrics
|
||||
- **Non-Functional Requirements are banned**: Drop any NFR content found in source docs instead of converting it into tables or IDs
|
||||
|
||||
**Architecture Tab** (`tab_architecture.html`):
|
||||
- `{{C4_CONTEXT}}` — System Context diagram (C4 Level 1)
|
||||
- `{{C4_CONTAINER}}` — Container diagram (C4 Level 2)
|
||||
- `{{C4_COMPONENT}}` — Component diagram (C4 Level 3)
|
||||
- `{{DEPLOYMENT_DIAGRAM}}` — Infrastructure deployment diagram
|
||||
- `{{ARCHITECTURE_NOTES}}` — Key architecture highlights table
|
||||
|
||||
**Technical Spec Tab** (`tab_technical_spec.html`):
|
||||
- `{{TECH_STACK_TABLE}}` — Full technology stack table with versions and purposes
|
||||
- `{{API_ENDPOINTS}}` — API endpoints tables (Authentication, Products, Cart, etc.)
|
||||
- `{{DATA_MODELS}}` — ER diagram + Data dictionary table
|
||||
- `{{TESTING_STRATEGY}}` — Risk-Based Testing approach and test pyramid
|
||||
|
||||
**Roadmap Tab** (`tab_roadmap.html`):
|
||||
- `{{EPIC_CARDS}}` — All Epic cards with In/Out Scope, Dependencies, Success Criteria, Progress
|
||||
- `{{OUT_OF_SCOPE_ITEMS}}` — Project-level out-of-scope items with reasons
|
||||
- `{{ROADMAP_LEGEND}}` — Status badges explanation
|
||||
|
||||
**Guides Tab** (`tab_guides.html`):
|
||||
- `{{GETTING_STARTED}}` — Prerequisites, Installation, Verification
|
||||
- `{{HOW_TO_GUIDES}}` — Step-by-step how-to guides (from guides/*.md)
|
||||
- `{{BEST_PRACTICES}}` — Code style, Testing approach, Design patterns
|
||||
- `{{TROUBLESHOOTING}}` — Common problems and solutions
|
||||
- `{{CONTRIBUTING}}` — Contributing guidelines
|
||||
- `{{EXTERNAL_RESOURCES}}` — Links to external documentation
|
||||
|
||||
**Placeholder Replacement Logic:**
|
||||
- Use **Edit** tool to replace `{{PLACEHOLDER}}` → actual content from project docs
|
||||
- For lists/arrays: generate HTML dynamically (e.g., loop through ADRs, create `<details>` elements)
|
||||
- For Kanban: parse kanban_board.md → calculate progress % → generate Epic card HTML
|
||||
- Preserve SCOPE tags in tab files (HTML comments at top)
|
||||
- Escape special characters to prevent XSS
|
||||
- Generate valid Mermaid syntax
|
||||
|
||||
### 6.3 Delete Example Blocks
|
||||
|
||||
**CRITICAL**: Remove all example content blocks to create project-specific presentation.
|
||||
|
||||
**Process**:
|
||||
1. **Search for example markers** in all 6 tab files:
|
||||
- Look for `<!-- EXAMPLE START: Remove this block after replacing placeholder -->`
|
||||
- Look for `<!-- EXAMPLE END -->`
|
||||
|
||||
2. **Delete example blocks** using Edit tool:
|
||||
- Remove everything between `<!-- EXAMPLE START -->` and `<!-- EXAMPLE END -->` (inclusive)
|
||||
- Do this for ALL occurrences across all 6 tab files
|
||||
- Leave only the actual project content that replaced `{{PLACEHOLDER}}` comments
|
||||
|
||||
3. **Validate cleanup**:
|
||||
- ✅ NO `<!-- EXAMPLE START -->` markers should remain
|
||||
- ✅ NO `<!-- EXAMPLE END -->` markers should remain
|
||||
- ✅ NO hardcoded e-commerce examples (John Smith, React 18 badges, Stripe, etc.)
|
||||
- ✅ Only actual project data should be visible in tab files
|
||||
|
||||
**Example transformation:**
|
||||
|
||||
**Before (dual-content template):**
|
||||
```html
|
||||
<!-- PLACEHOLDER: {{PROJECT_SUMMARY}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="project-summary">
|
||||
<h3>The Problem</h3>
|
||||
<p>Traditional e-commerce platforms struggle...</p>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
```
|
||||
|
||||
**After Step 6.2 (placeholder replaced):**
|
||||
```html
|
||||
<div class="project-summary">
|
||||
<h3>The Problem</h3>
|
||||
<p>Our healthcare system needs unified patient records...</p>
|
||||
</div>
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="project-summary">
|
||||
<h3>The Problem</h3>
|
||||
<p>Traditional e-commerce platforms struggle...</p>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
```
|
||||
|
||||
**After Step 6.3 (examples deleted):**
|
||||
```html
|
||||
<div class="project-summary">
|
||||
<h3>The Problem</h3>
|
||||
<p>Our healthcare system needs unified patient records...</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Output**: Clean, project-specific tab files with NO example content, ready for build
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Build Final Presentation
|
||||
|
||||
**Objective**: Assemble modular components into standalone HTML file.
|
||||
|
||||
**When to execute**: After Phase 6 (content injected, examples deleted)
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Check if presentation_final.html exists (Auto-rebuild for automation)**:
|
||||
- Use Glob tool: `pattern: "docs/presentation/presentation_final.html"`
|
||||
- If file exists:
|
||||
- **✓ Auto-rebuild** (generated file, safe operation)
|
||||
- Log: `ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)`
|
||||
- Continue to step 2
|
||||
- If NOT exists:
|
||||
- Log: `Creating presentation_final.html`
|
||||
- Continue to step 2
|
||||
|
||||
**Why auto-rebuild:**
|
||||
- presentation_final.html is a **generated file** (source of truth: assets/ directory)
|
||||
- Rebuilding is safe - no data loss (source files preserved in assets/)
|
||||
- Maintains fully automatic workflow when invoked by ln-110-documents-pipeline
|
||||
- User customizations in assets/ are preserved (only final HTML is regenerated)
|
||||
|
||||
2. **Navigate to presentation assets directory**:
|
||||
```bash
|
||||
cd docs/presentation/assets/
|
||||
```
|
||||
|
||||
3. **Run build script**:
|
||||
```bash
|
||||
node build-presentation.js
|
||||
```
|
||||
|
||||
4. **Build Script Process**:
|
||||
- **Step 1**: Read presentation_template.html
|
||||
- **Step 2**: Read and inline styles.css → `<style>` tag
|
||||
- **Step 3**: Read and inline scripts.js → `<script>` tag
|
||||
- **Step 4**: Read all 6 tab files → inject into empty `<div>` containers
|
||||
- **Step 5**: Replace {{PLACEHOLDERS}} with actual values
|
||||
- **Step 6**: Write `../presentation_final.html`
|
||||
|
||||
5. **Validate Output** (only if file was built):
|
||||
- Check file size (~120-150 KB expected)
|
||||
- Verify Mermaid diagrams syntax is valid
|
||||
- Log: `✓ Build completed successfully`
|
||||
|
||||
6. **Notify user**:
|
||||
- If rebuilt (file existed): `✓ Rebuilt docs/presentation/presentation_final.html (~120-150 KB)`
|
||||
- If created (file NOT existed): `✓ Created docs/presentation/presentation_final.html (~120-150 KB)`
|
||||
- Remind: `Test in browser: Double-click to open, or use http-server`
|
||||
|
||||
**Output**: docs/presentation/presentation_final.html (self-contained, ~120-150 KB, no external dependencies except Mermaid.js CDN)
|
||||
|
||||
**⚠️ Important Note:**
|
||||
|
||||
`presentation_final.html` is a **generated file** built from modular source files in `assets/`.
|
||||
|
||||
- ❌ **DO NOT edit `presentation_final.html` directly** — changes will be lost on next rebuild
|
||||
- ✅ **DO edit source files** in `assets/` directory (template, tabs, styles, scripts)
|
||||
- 🔄 **Rebuild after changes**: `cd assets/ && node build-presentation.js`
|
||||
|
||||
---
|
||||
|
||||
## Complete Output Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── project/ # Source documentation (input)
|
||||
│ ├── requirements.md
|
||||
│ ├── architecture.md
|
||||
│ ├── tech_stack.md
|
||||
│ ├── api_spec.md (conditional)
|
||||
│ ├── database_schema.md (conditional)
|
||||
│ ├── design_guidelines.md (conditional)
|
||||
│ └── runbook.md (conditional)
|
||||
├── reference/ # Source documentation (input)
|
||||
│ ├── adrs/
|
||||
│ │ └── *.md (Category: Strategic | Technical)
|
||||
│ └── guides/
|
||||
│ └── *.md (optional)
|
||||
├── tasks/ # Source documentation (input)
|
||||
│ └── kanban_board.md (Epic Story Counters)
|
||||
└── presentation/ # Output directory
|
||||
├── README.md # Navigation hub
|
||||
├── presentation_final.html # Final standalone HTML (~120-150 KB)
|
||||
└── assets/ # Modular HTML structure
|
||||
├── presentation_template.html # Base HTML5 + 6 tabs
|
||||
├── styles.css # ~400-500 lines
|
||||
├── scripts.js # Tab switching + Mermaid
|
||||
├── build-presentation.js # Node.js build script
|
||||
└── tabs/
|
||||
├── tab_overview.html # Landing page
|
||||
├── tab_requirements.html # FRs + ADRs
|
||||
├── tab_architecture.html # C4 diagrams
|
||||
├── tab_technical_spec.html # API + Data + Deployment
|
||||
├── tab_roadmap.html # Epic list
|
||||
└── tab_guides.html # How-to guides
|
||||
```
|
||||
|
||||
**Note**: Presentation READS from docs/project/, docs/reference/, docs/tasks/ but OUTPUTS to docs/presentation/.
|
||||
|
||||
---
|
||||
|
||||
## HTML Features
|
||||
|
||||
- **Single Source of Truth**: No information duplication - each piece lives in exactly ONE tab
|
||||
- **Landing Page (Overview)**: Problem/Solution/Business Value, Stakeholders, Documentation Guide, Quick Facts, Tech Stack badges
|
||||
- **Interactive Navigation**: 6 tabs with SCOPE tags, state persistence (localStorage), smooth transitions
|
||||
- **Table-Based Layout**: FRs table only (Non-Functional Requirements are forbidden), Architecture highlights table
|
||||
- **Roadmap Simplified**: Vertical Epic list with In/Out Scope sections, status badges, Dependencies/Success Criteria
|
||||
- **ADR Organization**: Grouped by category (Strategic/Technical) with accordion, full content inline
|
||||
- **Diagram Visualization**: Mermaid.js with tab-switch rerender (C4, ER, Sequence, Deployment)
|
||||
- **Responsive Design**: Mobile-first (320px/768px/1024px+ breakpoints)
|
||||
- **Collapsible Sections**: Auto-collapse with scroll preservation
|
||||
- **Modern UI**: Clean professional design, WCAG 2.1 Level AA compliant
|
||||
- **English Language**: All presentation content in English
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Idempotent Operation
|
||||
- ✅ Checks file existence before creation (presentation/README.md)
|
||||
- ✅ Auto-rebuild: Always rebuilds presentation_final.html (generated file)
|
||||
- ✅ Assets preservation: Skips copying templates if assets/ exists (preserves customizations)
|
||||
- ✅ Safe re-runs: Can invoke multiple times without data loss
|
||||
|
||||
### During Documentation Reading (Phase 1)
|
||||
- Validate paths: Check docs/ exists before reading
|
||||
- Graceful degradation: Continue if some files missing (warn user)
|
||||
- Extract metadata: Pull project name, date, version
|
||||
- Parse Mermaid blocks: Preserve diagram syntax
|
||||
|
||||
### During Source Validation (Phase 2/3)
|
||||
- **Phase 2**: STOP execution if required files missing (requirements.md, architecture.md, tech_stack.md)
|
||||
- **Phase 3**: WARN about quality issues but don't block (missing diagrams, placeholders, sparse content)
|
||||
- Provide actionable suggestions: "Run ln-114 to complete docs"
|
||||
- Read-only: Never edit source docs
|
||||
|
||||
### During Template Copying (Phase 5)
|
||||
- Check existing assets: Don't overwrite user-customized templates
|
||||
- Verify directory structure: Ensure tabs/ subdirectory created
|
||||
- Preserve permissions: Maintain executable permissions for build script
|
||||
|
||||
### During Content Injection & Cleanup (Phase 6)
|
||||
- Preserve Markdown formatting: Convert MD → HTML correctly
|
||||
- Generate valid Mermaid syntax: Test all diagram syntax
|
||||
- Escape special characters: Prevent XSS vulnerabilities
|
||||
- Use semantic HTML: Proper heading hierarchy, ARIA labels
|
||||
- Preserve SCOPE tags: Keep HTML comments in tab files
|
||||
- **Complete example cleanup**: Ensure ALL example blocks deleted
|
||||
- **Verify project-specific content**: NO hardcoded e-commerce examples in final tabs
|
||||
|
||||
### During Build (Phase 7)
|
||||
- Validate Node.js availability: Check `node --version` before running
|
||||
- Handle errors gracefully: Provide clear error messages
|
||||
- Test output: Open presentation_final.html to verify rendering
|
||||
- Size check: Warn if file >200 KB (may indicate issues)
|
||||
|
||||
---
|
||||
|
||||
## Customization Options
|
||||
|
||||
Edit `assets/styles.css` (CSS variables for theming), `assets/presentation_template.html` (layout/tabs), or `assets/tabs/*.html` (tab content).
|
||||
|
||||
**⚠️ After any customization:** Always rebuild the presentation:
|
||||
```bash
|
||||
cd assets/
|
||||
node build-presentation.js
|
||||
```
|
||||
|
||||
**Important:** Never edit `presentation_final.html` directly — it's a generated file that gets overwritten on each build.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Orchestrator**: ln-110-documents-pipeline (invokes this worker in final step)
|
||||
|
||||
**Standalone usage**: Can also be invoked directly for:
|
||||
- Rebuilding HTML presentation after documentation updates
|
||||
- Creating standalone presentation for existing docs
|
||||
- Validating source documentation readiness
|
||||
|
||||
**Source Documentation Requirements**:
|
||||
- **Required files** (must exist):
|
||||
- docs/project/requirements.md
|
||||
- docs/project/architecture.md
|
||||
- docs/project/tech_stack.md
|
||||
- **Optional files** (enhance presentation):
|
||||
- docs/project/api_spec.md, database_schema.md, design_guidelines.md, runbook.md
|
||||
- docs/reference/adrs/*.md (with Category field)
|
||||
- docs/reference/guides/*.md
|
||||
- docs/tasks/kanban_board.md
|
||||
|
||||
**Quality Recommendations** (warnings only, not blocking):
|
||||
- architecture.md should have Mermaid diagrams (C4 Context/Container/Component)
|
||||
- database_schema.md should have ER diagram
|
||||
- Source docs should NOT contain placeholders (`{{PLACEHOLDER}}`, `[Add your...]`)
|
||||
- Minimum content length: requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words
|
||||
|
||||
**Dependencies**:
|
||||
- Node.js v18+ (for build-presentation.js)
|
||||
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
|
||||
- Internet connection (Mermaid.js CDN, optional)
|
||||
|
||||
**Idempotent**: Yes - can be invoked multiple times without side effects:
|
||||
- Preserves existing README.md
|
||||
- Preserves existing assets/ (user customizations)
|
||||
- Always rebuilds presentation_final.html (generated file)
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
| Phase | Critical Checkpoints |
|
||||
|-------|---------------------|
|
||||
| **1. READ DOCS** | ✅ All docs loaded from docs/project/, docs/reference/, docs/tasks/ ✅ Metadata extracted ✅ Mermaid blocks preserved |
|
||||
| **2. VALIDATE EXISTS** | ✅ Required files exist (requirements.md, architecture.md, tech_stack.md) ✅ ERROR if missing |
|
||||
| **3. VALIDATE QUALITY** | ✅ Diagrams checked ✅ Placeholders detected ✅ Content length checked ✅ WARN only (non-blocking) |
|
||||
| **4. CREATE DIR** | ✅ docs/presentation/ created ✅ README.md created/preserved |
|
||||
| **5. COPY TEMPLATES** | ✅ assets/ created with all templates OR preserved if exists |
|
||||
| **6. INJECT CONTENT** | ✅ All 6 tabs populated ✅ **CRITICAL: Example blocks deleted** ✅ No `<!-- EXAMPLE -->` markers ✅ No hardcoded e-commerce data |
|
||||
| **7. BUILD HTML** | ✅ `node build-presentation.js` executed ✅ presentation_final.html created (~120-150 KB) ✅ Tested in browser |
|
||||
|
||||
**Output:** docs/presentation/presentation_final.html + assets/ + README.md
|
||||
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
User: "Build HTML presentation"
|
||||
|
||||
Process:
|
||||
1. **READ DOCS** - Load documentation from docs/project/, docs/reference/, docs/tasks/
|
||||
2. **VALIDATE SOURCE EXISTS** - Check requirements.md, architecture.md, tech_stack.md exist (ERROR if missing)
|
||||
3. **VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (WARN if issues, but continue)
|
||||
4. **CREATE DIR** - Create docs/presentation/ + README.md navigation hub
|
||||
5. **COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/ (or preserve existing)
|
||||
6. **INJECT CONTENT** - Parse MD docs → replace placeholders in tabs → delete example blocks
|
||||
7. **BUILD HTML** - Assemble modular components → standalone presentation_final.html (~120-150 KB)
|
||||
|
||||
Output: docs/presentation/presentation_final.html (6 tabs: Overview, Requirements, Architecture, Technical Spec, Roadmap, Guides) + docs/presentation/README.md (navigation hub) + docs/presentation/assets/ (modular source files)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **ERROR: Missing required files**: Run ln-114-project-docs-creator to create requirements.md, architecture.md, tech_stack.md
|
||||
- **WARN: Missing diagrams**: Add Mermaid diagrams to architecture.md (C4 Context/Container/Component) and database_schema.md (ER diagram)
|
||||
- **WARN: Placeholders found**: Complete documentation in source MD files before building
|
||||
- **WARN: Sparse content**: Expand documentation (requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words)
|
||||
- **Build script fails**: Check Node.js v18+, navigate to assets/, verify all files exist
|
||||
- **Mermaid diagrams not rendering**: Check syntax with Mermaid Live Editor, verify CDN loaded
|
||||
- **Tabs not switching**: Check JavaScript loaded, open browser console for errors
|
||||
- **File too large (>200 KB)**: Reduce diagrams, minify CSS/JS, remove unused rules
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
**Standards**: HTML5, CSS3 (Flexbox/Grid/Variables), ES6+, WCAG 2.1 Level AA, Mobile-first responsive design, Progressive enhancement, Mermaid.js v11
|
||||
|
||||
**Dependencies**:
|
||||
- Node.js v18+ (build script)
|
||||
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
|
||||
- Internet connection (Mermaid.js CDN, optional)
|
||||
|
||||
**Language**: English only (all presentation content)
|
||||
|
||||
---
|
||||
|
||||
**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation (source docs existence + content quality). Removed ln-120-docs-validator references. Renumbered phases (2-5 → 4-7). Unified READ+VALIDATE+CREATE workflow. Read-only source validation.)
|
||||
**Last Updated:** 2025-11-18
|
||||
102
skills/ln-115-presentation-creator/diagram.html
Normal file
102
skills/ln-115-presentation-creator/diagram.html
Normal file
@@ -0,0 +1,102 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>ln-115-presentation-creator - State Diagram</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
|
||||
<link rel="stylesheet" href="../shared/css/diagram.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<header>
|
||||
<h1>🎨 ln-115-presentation-creator</h1>
|
||||
<p class="subtitle">Interactive HTML Presentation Creator - State Diagram</p>
|
||||
</header>
|
||||
|
||||
<div class="info-box">
|
||||
<h3>📋 Workflow Overview</h3>
|
||||
<ul>
|
||||
<li><strong>Purpose:</strong> Build interactive HTML presentation from project documentation</li>
|
||||
<li><strong>Output:</strong> Single HTML file with 6 tabs (Overview, Requirements, Architecture, Technical Spec, Roadmap, Guides)</li>
|
||||
<li><strong>Technologies:</strong> Mermaid v11, table-based structure, English language</li>
|
||||
<li><strong>Use after:</strong> ln-114-project-docs-creator or invoked automatically by ln-110-documents-pipeline (Phase 2.5)</li>
|
||||
<li><strong>Validation:</strong> Phase 2 source docs existence + Phase 3 content quality validation (read-only)</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="legend">
|
||||
<div class="legend-item">
|
||||
<div class="legend-color color-discovery"></div>
|
||||
<span>Discovery/Validation</span>
|
||||
</div>
|
||||
<div class="legend-item">
|
||||
<div class="legend-color color-processing"></div>
|
||||
<span>Content Processing</span>
|
||||
</div>
|
||||
<div class="legend-item">
|
||||
<div class="legend-color color-action"></div>
|
||||
<span>Output Generation</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="diagram-container">
|
||||
<div class="mermaid">
|
||||
graph TD
|
||||
Start([Start: Build HTML Presentation]) --> Phase1[Phase 1: Read Source Documents<br/>Requirements, Architecture, Tech Spec, ADRs, Guides]
|
||||
|
||||
Phase1 --> Phase2[Phase 2: Validate Source Exists<br/>Check required/optional files]
|
||||
|
||||
Phase2 --> Phase3[Phase 3: Validate Content Quality<br/>Mermaid diagrams, placeholders, min length]
|
||||
|
||||
Phase3 --> Phase4[Phase 4: Create Presentation Directory<br/>docs/presentation/ + README.md]
|
||||
|
||||
Phase4 --> Phase5[Phase 5: Copy Templates to Project<br/>12 HTML/CSS/JS template files]
|
||||
|
||||
Phase5 --> Phase6[Phase 6: Content Injection<br/>Build 6 tabs + parse Mermaid + cleanup examples]
|
||||
|
||||
Phase6 --> Phase7[Phase 7: Build Final HTML<br/>Combine tabs + CSS + JS → presentation_final.html]
|
||||
|
||||
Phase7 --> End([End: ✓ Interactive presentation created])
|
||||
|
||||
%% Styling
|
||||
classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
|
||||
classDef processing fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
|
||||
classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
|
||||
|
||||
class Phase1,Phase2,Phase3 discovery
|
||||
class Phase4,Phase5,Phase6 processing
|
||||
class Phase7 action
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="info-box">
|
||||
<h3>🔑 Key Features</h3>
|
||||
<ul>
|
||||
<li><strong>6 Tabs:</strong> Overview (landing), Requirements (FRs/ADRs only; Non-Functional Requirements forbidden), Architecture (C4), Technical Spec (API/data), Roadmap (Kanban), Guides</li>
|
||||
<li><strong>Diátaxis Framework:</strong> Structured documentation approach</li>
|
||||
<li><strong>SCOPE Tags:</strong> Each tab has defined scope boundaries</li>
|
||||
<li><strong>Template Ownership:</strong> All HTML/CSS/JS templates in references/ directory (12 files)</li>
|
||||
<li><strong>Unified Workflow:</strong> READ+VALIDATE+CREATE with Phase 2/3 validation, renumbered phases (2-5 → 4-7)</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<footer>
|
||||
<p>Generated for ln-115-presentation-creator skill | Version 7.0.0</p>
|
||||
<p>Diagram format: Mermaid.js | Last updated: 2025-11-18</p>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
mermaid.initialize({
|
||||
startOnLoad: true,
|
||||
theme: 'default',
|
||||
flowchart: {
|
||||
useMaxWidth: true,
|
||||
htmlLabels: true,
|
||||
curve: 'basis'
|
||||
}
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
2288
skills/ln-115-presentation-creator/presentation_final.html
Normal file
2288
skills/ln-115-presentation-creator/presentation_final.html
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,302 @@
|
||||
# x-html-builder Template Architecture
|
||||
|
||||
This document describes the structure and content specifications for all HTML templates used by x-html-builder skill.
|
||||
|
||||
## File Structure
|
||||
|
||||
All templates are stored in `x-html-builder/references/` following the Template Ownership Principle (each skill owns its templates):
|
||||
|
||||
```
|
||||
x-html-builder/references/
|
||||
├── presentation_template.html # Base HTML5 structure with 6 tab navigation
|
||||
├── styles.css # CSS Variables, responsive design (~500 lines)
|
||||
├── scripts.js # Tab switching, collapsible sections, Mermaid init
|
||||
├── build-presentation.js # Node.js build script for inlining
|
||||
└── tabs/
|
||||
├── tab_overview_template.html # Landing page
|
||||
├── tab_requirements_template.html # FRs + ADRs (Non-Functional Requirements are forbidden)
|
||||
├── tab_architecture_template.html # C4 diagrams
|
||||
├── tab_technical_spec_template.html # API + Data + Deployment
|
||||
├── tab_roadmap_template.html # Kanban-style
|
||||
└── tab_guides_template.html # How-to guides
|
||||
```
|
||||
|
||||
## Tab Content Specifications
|
||||
|
||||
### Tab 1: Overview (Landing Page)
|
||||
|
||||
**File:** `tab_overview_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: Project name, tagline, business goal, tech stack badges, role-based navigation, quick stats, recent updates
|
||||
- EXCLUDES: Full requirements → Requirements tab, Detailed diagrams → Architecture tab, Full roadmap → Roadmap tab, API details → Technical Spec tab
|
||||
|
||||
**Content Elements:**
|
||||
- **Header Intro:** Project name (h1) + tagline (minimal, no gradient background)
|
||||
- **Project Summary:** Business goal in "About This Project" section (h2)
|
||||
- **Role-Based Navigation:** 4 cards (Developer/Architect/Product Owner/Stakeholder) - clickable, switches to relevant tab
|
||||
- **Tech Stack Badges:** Technology badges with icons and names
|
||||
- **Quick Stats:** Project statistics grid (total epics, completed stories, test coverage, uptime SLA)
|
||||
- **Recent Updates:** Recent project updates list
|
||||
- **Quick Links:** Links to other tabs (Requirements, Architecture, API Reference, Roadmap)
|
||||
|
||||
**Data Sources:**
|
||||
- requirements.md (project name, business goal)
|
||||
- architecture.md (tech stack)
|
||||
- kanban_board.md (stats, recent updates)
|
||||
|
||||
**Placeholders:**
|
||||
- `{{PROJECT_NAME}}` - Project name from requirements.md ## Project Name
|
||||
- `{{PROJECT_TAGLINE}}` - Short description from requirements.md
|
||||
- `{{BUSINESS_GOAL}}` - Business goals section from requirements.md
|
||||
- `{{TECH_STACK_BADGES}}` - Generated from architecture.md tech stack
|
||||
- `{{QUICK_STATS}}` - Generated from kanban_board.md Epic Story Counters
|
||||
- `{{RECENT_UPDATES}}` - Placeholder (currently undefined - TODO: specify data source)
|
||||
|
||||
### Tab 2: Requirements
|
||||
|
||||
**File:** `tab_requirements_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: Business goals, FRs (collapsible), ADRs (Strategic/Technical groups), constraints, success criteria
|
||||
- EXCLUDES: Implementation details → Technical Spec, Diagrams → Architecture, Code → Guides, Non-Functional Requirements (explicitly banned from this tab)
|
||||
|
||||
**Content Elements:**
|
||||
- **Business Goals:** Project objectives with key targets (h2 + list)
|
||||
- **Functional Requirements:** Collapsible by domain (details/summary tags) - FR-XXX-001 format with Priority (MUST/SHOULD/COULD), Description
|
||||
- **ADRs Section:** Grouped by category:
|
||||
- **Strategic Decisions** (h3) - Business/architecture strategy ADRs
|
||||
- **Technical Decisions** (h3) - Technology/implementation ADRs
|
||||
- Each ADR in accordion (details/summary) with full content inline:
|
||||
- Date | Status | Category (metadata line)
|
||||
- Context (h4)
|
||||
- Decision (h4)
|
||||
- Rationale (h4 + list)
|
||||
- Alternatives Considered (h4 + table: Alternative | Pros | Cons | Rejection Reason)
|
||||
- Consequences (h4 + Positive/Negative lists)
|
||||
- **Constraints:** Technology constraints
|
||||
- **Success Criteria:** Measurable project success metrics
|
||||
|
||||
**Data Sources:**
|
||||
- requirements.md (business goals, FRs, constraints, success criteria)
|
||||
- adrs/*.md (all ADR files with Category field for grouping)
|
||||
|
||||
**Note:** Do not add Non-Functional Requirements (performance, security, scalability, etc.). If quality topics need coverage, describe them as architecture quality goals in narrative form only—never as NFR-XXX-001 style requirements.
|
||||
|
||||
**Placeholders:**
|
||||
- None (all content directly from MD files)
|
||||
|
||||
### Tab 3: Architecture
|
||||
|
||||
**File:** `tab_architecture_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: C4 diagrams (Context/Container/Component), Deployment, Solution strategy, Quality attributes
|
||||
- EXCLUDES: ADRs → Requirements, API details → Technical Spec, Code → Guides
|
||||
|
||||
**Content Elements:**
|
||||
- **C4 Diagrams:** 4 levels in Mermaid syntax (preserved exactly as in architecture.md):
|
||||
- System Context (C4 Level 1)
|
||||
- Container Diagram (C4 Level 2)
|
||||
- Component Diagram (C4 Level 3)
|
||||
- Deployment Diagram
|
||||
- **Solution Strategy:** Architecture pattern, API design approach
|
||||
- **Quality Attributes:** Scalability, Security, Maintainability approaches
|
||||
|
||||
**Data Sources:**
|
||||
- architecture.md (all content)
|
||||
|
||||
**Placeholders:**
|
||||
- None (all content directly from architecture.md)
|
||||
|
||||
**EXCLUDES:**
|
||||
- Tech stack table → moved to Technical Spec tab
|
||||
- ADRs → moved to Requirements tab
|
||||
|
||||
### Tab 4: Technical Specification
|
||||
|
||||
**File:** `tab_technical_spec_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: Tech stack (detailed table), API endpoints, Authentication, Error codes, ER diagram, Data dictionary, Integrations, Deployment, Testing strategy (Risk-Based)
|
||||
- EXCLUDES: Requirements → Requirements tab, Architecture diagrams → Architecture tab, How-to guides → Guides tab
|
||||
|
||||
**Content Elements:**
|
||||
- **Technology Stack:** Detailed table (Category | Technology | Version | Purpose) - includes Frontend, Backend, Database, Infrastructure, DevOps categories
|
||||
- **API Endpoints:** Table grouped by resource (Endpoint | Method | Description | Request | Response)
|
||||
- **Authentication:** Auth mechanism description (JWT, OAuth, etc.)
|
||||
- **Error Codes:** Standard error codes table (Code | Message | Description)
|
||||
- **Data Model:** ER diagram in Mermaid + Data Dictionary table (Entity | Attributes | Description)
|
||||
- **Third-Party Integrations:** External services table (Service | Purpose | API Documentation)
|
||||
- **Deployment Infrastructure:** Infrastructure description (cloud provider, services)
|
||||
- **Testing Strategy:** Risk-Based Testing approach (2-5 E2E, 3-8 Integration, 5-15 Unit tests per Story, total 10-28 max)
|
||||
|
||||
**Data Sources:**
|
||||
- technical_specification.md (all content)
|
||||
- architecture.md (tech stack section - moved here)
|
||||
|
||||
**Placeholders:**
|
||||
- None (all content directly from MD files)
|
||||
|
||||
### Tab 5: Roadmap
|
||||
|
||||
**File:** `tab_roadmap_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: Kanban board (3 columns), Epic cards, Progress bars (%), Milestones
|
||||
- EXCLUDES: Individual stories → Linear, Daily tasks → task tracker, Team assignments, Implementation details → Technical Spec
|
||||
|
||||
**Content Elements:**
|
||||
- **Kanban Board:** 3 columns layout (Todo | In Progress | Done)
|
||||
- **Epic Cards:** For each Epic from kanban_board.md:
|
||||
- Epic number + title (h3)
|
||||
- Description (p)
|
||||
- Stories count: X/Y completed
|
||||
- Target date or Completed date
|
||||
- Status badge (status-todo | status-progress | status-done)
|
||||
- Progress bar with % width
|
||||
- **Milestones:** Quarterly milestones list with status indicators
|
||||
|
||||
**Data Sources:**
|
||||
- kanban_board.md (Epic Story Counters table - Epic number, title, status, story counts, target dates)
|
||||
- requirements.md (Epic descriptions)
|
||||
- architecture.md (Epic technical context)
|
||||
|
||||
**Placeholders:**
|
||||
- None (all content generated from kanban_board.md)
|
||||
|
||||
**Epic Status Mapping:**
|
||||
- Todo → kanban-todo column, status-todo badge, 0% progress
|
||||
- In Progress → kanban-progress column, status-progress badge, calculated % progress
|
||||
- Done → kanban-done column, status-done badge, 100% progress
|
||||
|
||||
### Tab 6: Guides
|
||||
|
||||
**File:** `tab_guides_template.html`
|
||||
|
||||
**SCOPE:**
|
||||
- INCLUDES: Getting started, How-to guides (task-oriented), Best practices, Troubleshooting, Contributing, External resources
|
||||
- EXCLUDES: API reference → Technical Spec, Architecture → Architecture tab, Requirements → Requirements tab
|
||||
|
||||
**Content Elements:**
|
||||
- **Getting Started:** Prerequisites, Installation steps (code blocks), Verification checklist
|
||||
- **How-To Guides:** Task-oriented guides (How to Add Product, How to Test API, etc.) - steps in ordered lists
|
||||
- **Best Practices:** Code style, Testing approach, Design patterns
|
||||
- **Troubleshooting:** Common issues with solutions (h3 per issue + list)
|
||||
- **Contributing Guidelines:** Fork, branch, test, submit PR workflow
|
||||
- **External Resources:** Links to framework docs, third-party docs (target="_blank")
|
||||
|
||||
**Data Sources:**
|
||||
- docs/guides/*.md (all guide files)
|
||||
- README.md (getting started section)
|
||||
- technical_specification.md (testing strategy)
|
||||
|
||||
**Placeholders:**
|
||||
- None (all content directly from guide files)
|
||||
|
||||
## Build Process
|
||||
|
||||
**Script:** `build-presentation.js` (Node.js)
|
||||
|
||||
**Logic:**
|
||||
1. Read `presentation_template.html`
|
||||
2. Read all 6 tab files from `tabs/` directory
|
||||
3. Inject tab content into template (replace `<!-- TAB_CONTENT_overview -->` etc.)
|
||||
4. Read `styles.css` and inline into `<style>` tags
|
||||
5. Read `scripts.js` and inline into `<script>` tags
|
||||
6. Write `../presentation_final.html` (one level up from assets/)
|
||||
|
||||
**Expected Output:**
|
||||
- Standalone HTML file (~120-150 KB)
|
||||
- No external dependencies (except Mermaid.js CDN for diagram rendering)
|
||||
- All CSS and JavaScript inlined
|
||||
|
||||
## Styling Specifications
|
||||
|
||||
**File:** `styles.css` (~500 lines)
|
||||
|
||||
**CSS Variables:**
|
||||
```css
|
||||
:root {
|
||||
--primary-color: #2563eb;
|
||||
--background-color: #f8fafc;
|
||||
--text-color: #1e293b;
|
||||
--border-color: #e2e8f0;
|
||||
}
|
||||
```
|
||||
|
||||
**Key Components:**
|
||||
- **header-intro:** Minimal header (no gradient) - name + tagline
|
||||
- **project-summary:** Business goal section (h2 + paragraph)
|
||||
- **role-cards:** 4 clickable cards with hover effects (subtle, no transform)
|
||||
- **badge:** Tech stack badges (inline-block, rounded, neutral colors)
|
||||
- **epic-card:** Roadmap Epic cards with status badges and progress bars
|
||||
- **progress-bar:** Horizontal bar with % fill (neutral colors, no gradient)
|
||||
- **tabs:** Navigation bar with active tab indicator
|
||||
- **kanban-board:** 3-column grid layout
|
||||
- **Mermaid diagrams:** Responsive container with max-width
|
||||
- **ADR accordion:** details/summary styling with expand indicator
|
||||
- **Responsive breakpoints:** Mobile (<768px), Tablet (768-1024px), Desktop (>1024px)
|
||||
|
||||
**Design Principles:**
|
||||
- Minimal, documentation-focused (vs marketing-style)
|
||||
- Neutral color palette (blues, grays)
|
||||
- No excessive gradients or transforms
|
||||
- GitBook/Docusaurus aesthetic
|
||||
- Progressive disclosure (collapsible sections)
|
||||
- Information scent (clear navigation labels)
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before completing build, verify:
|
||||
|
||||
- [ ] HTML structure valid (proper heading hierarchy h1 > h2 > h3)
|
||||
- [ ] All 6 tabs present in navigation (overview, requirements, architecture, technical_spec, roadmap, guides)
|
||||
- [ ] SCOPE tags present in each tab (HTML comments in first 3-5 lines)
|
||||
- [ ] All placeholders replaced (no `{{PLACEHOLDER}}` remaining)
|
||||
- [ ] Mermaid diagrams render correctly (valid syntax, no errors in console)
|
||||
- [ ] Tab switching works (JavaScript loaded, localStorage state persistence)
|
||||
- [ ] Collapsible sections functional (details/summary expand/collapse)
|
||||
- [ ] Responsive design works (mobile/tablet/desktop breakpoints)
|
||||
- [ ] Kanban board renders: 3 columns, Epic cards in correct columns, progress bars display %
|
||||
- [ ] ADR grouping works: Strategic/Technical sections separate, accordion expands/collapses
|
||||
- [ ] Role-based navigation cards clickable (switches to correct tabs)
|
||||
- [ ] File size within expected range (~120-150 KB)
|
||||
- [ ] Tested in browser: Double-click presentation_final.html → opens without errors
|
||||
|
||||
## Data Source Mapping
|
||||
|
||||
| Tab | Primary Source | Secondary Sources |
|
||||
|-----|---------------|-------------------|
|
||||
| Overview | requirements.md | architecture.md, kanban_board.md |
|
||||
| Requirements | requirements.md | adrs/*.md |
|
||||
| Architecture | architecture.md | - |
|
||||
| Technical Spec | technical_specification.md | architecture.md (tech stack) |
|
||||
| Roadmap | kanban_board.md | requirements.md, architecture.md |
|
||||
| Guides | docs/guides/*.md | README.md, technical_specification.md |
|
||||
|
||||
## Placeholder Reference
|
||||
|
||||
| Placeholder | Source | Location |
|
||||
|-------------|--------|----------|
|
||||
| `{{PROJECT_NAME}}` | requirements.md | ## Project Name |
|
||||
| `{{PROJECT_TAGLINE}}` | requirements.md | First paragraph or subtitle |
|
||||
| `{{BUSINESS_GOAL}}` | requirements.md | ## Business Goals section |
|
||||
| `{{TECH_STACK_BADGES}}` | architecture.md | ## Technology Stack section |
|
||||
| `{{QUICK_STATS}}` | kanban_board.md | Epic Story Counters table |
|
||||
| `{{RECENT_UPDATES}}` | **TODO: Undefined** | Need to specify data source |
|
||||
|
||||
## TODO: Undefined Placeholders
|
||||
|
||||
**RECENT_UPDATES:**
|
||||
- **Current Status:** Placeholder exists in tab_overview_template.html but data source not specified
|
||||
- **Recommendation:** Either:
|
||||
1. Remove placeholder if not needed
|
||||
2. Define data source (e.g., git log last 5 commits, or manual section in requirements.md)
|
||||
3. Generate from kanban_board.md Epic status changes
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-01-31
|
||||
**Related:** x-html-builder/SKILL.md
|
||||
@@ -0,0 +1,67 @@
|
||||
/**
|
||||
* Build Script for HTML Presentation
|
||||
*
|
||||
* Reads modular HTML components and creates standalone presentation_final.html
|
||||
* by inlining CSS, JavaScript, and all tab content.
|
||||
*
|
||||
* Usage: node build-presentation.js (run from assets/ directory)
|
||||
* Output: ../presentation_final.html
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
console.log('🔨 Building presentation...\n');
|
||||
|
||||
// 1. Read base template
|
||||
console.log('📄 Reading presentation_template.html...');
|
||||
let html = fs.readFileSync('presentation_template.html', 'utf-8');
|
||||
|
||||
// 2. Read and inject tab content
|
||||
const tabs = ['overview', 'requirements', 'architecture', 'technical_spec', 'roadmap', 'guides'];
|
||||
console.log('📑 Injecting tab content...');
|
||||
|
||||
tabs.forEach(tab => {
|
||||
const tabFile = path.join('tabs', `tab_${tab}.html`);
|
||||
if (fs.existsSync(tabFile)) {
|
||||
const tabContent = fs.readFileSync(tabFile, 'utf-8');
|
||||
const placeholder = `<!--TAB_${tab.toUpperCase()}-->`;
|
||||
html = html.replace(placeholder, tabContent);
|
||||
console.log(` ✓ ${tab}`);
|
||||
} else {
|
||||
console.log(` ⚠ ${tab} (file not found, skipping)`);
|
||||
}
|
||||
});
|
||||
|
||||
// 3. Inline CSS
|
||||
console.log('🎨 Inlining styles.css...');
|
||||
if (fs.existsSync('styles.css')) {
|
||||
const css = fs.readFileSync('styles.css', 'utf-8');
|
||||
html = html.replace('<!--STYLES-->', `<style>\n${css}\n</style>`);
|
||||
console.log(' ✓ CSS inlined');
|
||||
} else {
|
||||
console.log(' ⚠ styles.css not found');
|
||||
}
|
||||
|
||||
// 4. Inline JavaScript
|
||||
console.log('⚡ Inlining scripts.js...');
|
||||
if (fs.existsSync('scripts.js')) {
|
||||
const js = fs.readFileSync('scripts.js', 'utf-8');
|
||||
html = html.replace('<!--SCRIPTS-->', `<script>\n${js}\n</script>`);
|
||||
console.log(' ✓ JS inlined');
|
||||
} else {
|
||||
console.log(' ⚠ scripts.js not found');
|
||||
}
|
||||
|
||||
// 5. Write final presentation
|
||||
const outputPath = path.join('..', 'presentation_final.html');
|
||||
console.log(`\n📦 Writing ${outputPath}...`);
|
||||
fs.writeFileSync(outputPath, html, 'utf-8');
|
||||
|
||||
// 6. Calculate file size
|
||||
const stats = fs.statSync(outputPath);
|
||||
const sizeKB = (stats.size / 1024).toFixed(2);
|
||||
console.log(` ✓ File size: ${sizeKB} KB`);
|
||||
|
||||
console.log('\n✅ Build complete!');
|
||||
console.log(` Open: ${outputPath}`);
|
||||
@@ -0,0 +1,389 @@
|
||||
# Mermaid.js Guidelines for x-html-builder
|
||||
|
||||
This guide provides best practices for working with Mermaid.js diagrams in HTML presentations with tab-based navigation.
|
||||
|
||||
## Version and CDN
|
||||
|
||||
**Current Version:** Mermaid v11.12.1 (latest stable as of 2025)
|
||||
|
||||
**Recommended CDN:**
|
||||
```html
|
||||
<!-- Standard version -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
|
||||
<!-- ESM version (modern browsers) -->
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||||
</script>
|
||||
```
|
||||
|
||||
**Why v11?**
|
||||
- Latest features and bug fixes
|
||||
- Improved performance
|
||||
- Better error handling
|
||||
- `mermaid.init()` deprecated (use `mermaid.run()` instead)
|
||||
|
||||
---
|
||||
|
||||
## Initialization for Tab-Based Presentations
|
||||
|
||||
**Critical Setting:** `startOnLoad: false`
|
||||
|
||||
**Why?**
|
||||
- Tabs with `display: none` prevent diagrams from rendering correctly
|
||||
- Diagrams need manual rendering when tab becomes visible
|
||||
- Allows precise control over rendering timing
|
||||
|
||||
**Configuration:**
|
||||
```javascript
|
||||
mermaid.initialize({
|
||||
startOnLoad: false, // Manual control for tab switching
|
||||
theme: 'default', // or 'dark', 'forest', 'neutral'
|
||||
securityLevel: 'loose', // For trusted content (allows HTML labels)
|
||||
logLevel: 1, // 0=none, 1=error, 2=warn, 3=info
|
||||
flowchart: {
|
||||
useMaxWidth: true, // Responsive diagrams
|
||||
htmlLabels: true // Rich text support
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rendering Strategies
|
||||
|
||||
### Strategy 1: Render Once Per Tab (Recommended)
|
||||
|
||||
**Best for:** Static content with tab navigation
|
||||
|
||||
```javascript
|
||||
document.addEventListener('DOMContentLoaded', async function() {
|
||||
// Initialize Mermaid
|
||||
mermaid.initialize({ startOnLoad: false });
|
||||
|
||||
// Render initially active tab
|
||||
const activeTab = document.querySelector('.tab-content.active');
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true'; // Mark as rendered
|
||||
}
|
||||
});
|
||||
|
||||
async function switchTab(tabName) {
|
||||
// ... tab switching logic ...
|
||||
|
||||
// Render diagrams only if not already rendered
|
||||
const activeTab = document.getElementById(`${tabName}-tab`);
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Performance: Each tab rendered only once
|
||||
- ✅ No duplicate diagrams
|
||||
- ✅ Minimal re-rendering overhead
|
||||
|
||||
### Strategy 2: Render All on Load
|
||||
|
||||
**Best for:** Small number of tabs (<5), simple diagrams
|
||||
|
||||
```javascript
|
||||
document.addEventListener('DOMContentLoaded', async function() {
|
||||
mermaid.initialize({ startOnLoad: false });
|
||||
|
||||
// Render ALL diagrams at once
|
||||
await mermaid.run({
|
||||
querySelector: '.mermaid',
|
||||
suppressErrors: true
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Simple implementation
|
||||
- ✅ No tab-switch delays
|
||||
- ❌ Slower initial load for many diagrams
|
||||
|
||||
### Strategy 3: Manual Rendering API
|
||||
|
||||
**Best for:** Dynamic content from API, programmatic diagram generation
|
||||
|
||||
```javascript
|
||||
const graphDefinition = `
|
||||
graph TD
|
||||
A[Client] --> B[Load Balancer]
|
||||
B --> C[Server1]
|
||||
B --> D[Server2]
|
||||
`;
|
||||
|
||||
const { svg } = await mermaid.render('uniqueId', graphDefinition);
|
||||
document.getElementById('diagram-container').innerHTML = svg;
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Full control over rendering
|
||||
- ✅ Can modify SVG before insertion
|
||||
- ✅ Works with dynamic content
|
||||
|
||||
---
|
||||
|
||||
## Common Errors and Solutions
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| **Diagrams not rendering in hidden tabs** | `startOnLoad: true` + `display: none` | Use `startOnLoad: false` + `mermaid.run()` on tab switch |
|
||||
| **Duplicate diagrams** | Re-rendering already rendered content | Cache rendered tabs with `data-mermaid-rendered` attribute |
|
||||
| **"mermaid.init is deprecated"** | Using old API | Replace `mermaid.init()` with `mermaid.run()` |
|
||||
| **SVG sizing issues** | Rendering while element is hidden | Add `setTimeout(... , 50)` before rendering to ensure tab is visible |
|
||||
| **Parsing errors break page** | Invalid Mermaid syntax | Use `suppressErrors: true` in `mermaid.run()` |
|
||||
| **Fonts not loaded** | Rendering before fonts ready | Wait for `DOMContentLoaded` + small delay (50-100ms) |
|
||||
| **Different themes on tabs** | Theme not applied to new renders | Re-initialize theme before rendering: `mermaid.initialize({ theme: 'dark' })` |
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Lazy Rendering
|
||||
Only render diagrams when tab becomes visible (Strategy 1).
|
||||
|
||||
### 2. Caching
|
||||
Use `data-mermaid-rendered` attribute to avoid re-rendering:
|
||||
```javascript
|
||||
if (!element.dataset.mermaidRendered) {
|
||||
await mermaid.run({ nodes: [element] });
|
||||
element.dataset.mermaidRendered = 'true';
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Batch Rendering
|
||||
Render multiple diagrams in one `mermaid.run()` call:
|
||||
```javascript
|
||||
// Good: One call for all diagrams in tab
|
||||
await mermaid.run({ nodes: tab.querySelectorAll('.mermaid') });
|
||||
|
||||
// Bad: Multiple calls
|
||||
diagrams.forEach(d => mermaid.run({ nodes: [d] }));
|
||||
```
|
||||
|
||||
### 4. Error Suppression (Production)
|
||||
Prevent parsing errors from breaking the page:
|
||||
```javascript
|
||||
await mermaid.run({ suppressErrors: true });
|
||||
```
|
||||
|
||||
### 5. Async/Await
|
||||
Always use async/await for predictable rendering:
|
||||
```javascript
|
||||
async function renderDiagrams() {
|
||||
await mermaid.run({ ... }); // Wait for completion
|
||||
console.log('Rendering complete');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Levels
|
||||
|
||||
**Choose based on content trust level:**
|
||||
|
||||
### `loose` (Recommended for Documentation)
|
||||
```javascript
|
||||
mermaid.initialize({ securityLevel: 'loose' });
|
||||
```
|
||||
- Allows HTML labels
|
||||
- Allows some scripts in labels
|
||||
- **Use for:** Internal docs, trusted content
|
||||
|
||||
### `strict` (User-Generated Content)
|
||||
```javascript
|
||||
mermaid.initialize({ securityLevel: 'strict' });
|
||||
```
|
||||
- Blocks all scripts
|
||||
- Sanitizes HTML
|
||||
- **Use for:** User-submitted diagrams, public content
|
||||
|
||||
### `antiscript` (Middle Ground)
|
||||
```javascript
|
||||
mermaid.initialize({ securityLevel: 'antiscript' });
|
||||
```
|
||||
- Removes scripts from output
|
||||
- Allows safe HTML
|
||||
|
||||
---
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Complete Tab-Based Implementation
|
||||
|
||||
```javascript
|
||||
document.addEventListener('DOMContentLoaded', async function() {
|
||||
// Initialize Mermaid
|
||||
if (typeof mermaid !== 'undefined') {
|
||||
mermaid.initialize({
|
||||
startOnLoad: false,
|
||||
theme: 'default',
|
||||
securityLevel: 'loose',
|
||||
logLevel: 1,
|
||||
flowchart: {
|
||||
useMaxWidth: true,
|
||||
htmlLabels: true
|
||||
}
|
||||
});
|
||||
|
||||
// Render initially active tab
|
||||
setTimeout(async () => {
|
||||
const activeTab = document.querySelector('.tab-content.active');
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
try {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true';
|
||||
} catch (err) {
|
||||
console.error('Mermaid rendering error:', err);
|
||||
}
|
||||
}
|
||||
}, 100);
|
||||
}
|
||||
|
||||
// Tab switching
|
||||
async function switchTab(tabName) {
|
||||
// ... tab activation logic ...
|
||||
|
||||
// Render diagrams if not already rendered
|
||||
if (typeof mermaid !== 'undefined') {
|
||||
const activeTab = document.getElementById(`${tabName}-tab`);
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
setTimeout(async () => {
|
||||
try {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true';
|
||||
} catch (err) {
|
||||
console.error('Mermaid rendering error on tab switch:', err);
|
||||
}
|
||||
}, 50);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Error Handling with Fallback
|
||||
|
||||
```javascript
|
||||
async function renderMermaidSafe(element) {
|
||||
try {
|
||||
await mermaid.run({ nodes: [element] });
|
||||
} catch (err) {
|
||||
console.error('Mermaid error:', err);
|
||||
element.innerHTML = `
|
||||
<div style="color: red; padding: 10px; border: 1px solid red;">
|
||||
⚠️ Diagram rendering failed. Check syntax.
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes: v10 → v11
|
||||
|
||||
**Breaking Changes:**
|
||||
- ❌ `mermaid.init()` is deprecated → Use `mermaid.run()`
|
||||
- ⚠️ Some theme options renamed (check docs)
|
||||
|
||||
**Recommended Changes:**
|
||||
```javascript
|
||||
// Old (v10)
|
||||
mermaid.init(undefined, '.mermaid');
|
||||
|
||||
// New (v11)
|
||||
await mermaid.run({ querySelector: '.mermaid' });
|
||||
```
|
||||
|
||||
**CDN Update:**
|
||||
```html
|
||||
<!-- v10 -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
|
||||
|
||||
<!-- v11 -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
```
|
||||
|
||||
**Compatibility:**
|
||||
- ✅ All diagram types (flowchart, sequence, class, ER, etc.) work in v11
|
||||
- ✅ Themes are compatible
|
||||
- ✅ Configuration options mostly unchanged
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
When diagrams don't render:
|
||||
|
||||
1. **Check CDN loading:**
|
||||
```javascript
|
||||
console.log(typeof mermaid); // Should be 'object', not 'undefined'
|
||||
```
|
||||
|
||||
2. **Check initialization:**
|
||||
```javascript
|
||||
console.log(mermaid.initialize); // Should be a function
|
||||
```
|
||||
|
||||
3. **Check element visibility:**
|
||||
```javascript
|
||||
const el = document.querySelector('.mermaid');
|
||||
console.log(window.getComputedStyle(el).display); // Should NOT be 'none'
|
||||
```
|
||||
|
||||
4. **Check for syntax errors:**
|
||||
- Open browser console
|
||||
- Look for Mermaid parsing errors
|
||||
- Validate syntax at https://mermaid.live
|
||||
|
||||
5. **Check timing:**
|
||||
- Are you rendering before DOM is ready?
|
||||
- Is element visible when rendering?
|
||||
- Try adding `setTimeout(... , 100)` delay
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
✅ **DO:**
|
||||
- Use `startOnLoad: false` for tab-based layouts
|
||||
- Cache rendered tabs with `data-mermaid-rendered`
|
||||
- Use async/await for predictable rendering
|
||||
- Add error handling with `suppressErrors: true`
|
||||
- Wait for element visibility before rendering
|
||||
- Use `mermaid.run()` (not deprecated `init()`)
|
||||
|
||||
❌ **DON'T:**
|
||||
- Use `startOnLoad: true` with hidden tabs
|
||||
- Re-render already rendered diagrams
|
||||
- Render while element has `display: none`
|
||||
- Use `mermaid.init()` (deprecated)
|
||||
- Ignore parsing errors in production
|
||||
- Mix rendering strategies
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-11-06
|
||||
**Mermaid Version:** v11.12.1
|
||||
**Compatible with:** x-html-builder v2.3.1+
|
||||
@@ -0,0 +1,146 @@
|
||||
# {{PROJECT_NAME}} - Presentation
|
||||
|
||||
> **SCOPE:** Navigation hub for project presentation (HTML presentation access, customization guide, build instructions ONLY). DO NOT add here: Project documentation → docs/project/, Architecture details → docs/project/architecture.md, Technical specs → docs/project/tech_stack.md
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This directory contains the interactive HTML presentation for **{{PROJECT_NAME}}**, generated from project documentation (requirements, architecture, technical specifications).
|
||||
|
||||
**Use this when:**
|
||||
- Presenting project overview to stakeholders
|
||||
- Onboarding new team members
|
||||
- Sharing project architecture visually
|
||||
- Creating project demos
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
**Main Presentation:**
|
||||
- [presentation_final.html](presentation_final.html) - Open this in your browser
|
||||
|
||||
**Modular Structure:**
|
||||
- [assets/presentation_template.html](assets/presentation_template.html) - Base template
|
||||
- [assets/styles.css](assets/styles.css) - Styling
|
||||
- [assets/scripts.js](assets/scripts.js) - Tab switching logic
|
||||
- [assets/tabs/](assets/tabs/) - Individual tab content (tab_overview.html, tab_requirements.html, tab_architecture.html, tab_technical_spec.html, tab_roadmap.html, tab_guides.html)
|
||||
- [assets/build-presentation.js](assets/build-presentation.js) - Build script
|
||||
|
||||
**⚠️ IMPORTANT: presentation_final.html is a GENERATED file**
|
||||
- DO NOT edit presentation_final.html directly - changes will be overwritten on next build
|
||||
- ALL changes must be made in source files (tabs/*.html, styles.css, scripts.js, presentation_template.html)
|
||||
- Rebuild after source changes: `node docs/presentation/assets/build-presentation.js`
|
||||
|
||||
---
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### Editing Content
|
||||
|
||||
1. **Edit individual tabs** in `assets/tabs/`:
|
||||
- `tab_overview.html` - Project overview and key information
|
||||
- `tab_requirements.html` - Functional requirements and acceptance criteria
|
||||
- `tab_architecture.html` - System architecture and C4 diagrams
|
||||
- `tab_technical_spec.html` - Technology stack, API, database (or specialized tabs)
|
||||
- `tab_roadmap.html` - Project roadmap and milestones
|
||||
- `tab_guides.html` - Quick guides and best practices
|
||||
|
||||
2. **Update styles** in `assets/css/custom.css`:
|
||||
- Modify colors, fonts, spacing
|
||||
- Customize section backgrounds
|
||||
- Adjust diagram styles
|
||||
|
||||
3. **Modify behavior** in `assets/js/custom.js`:
|
||||
- Add custom interactions
|
||||
- Implement navigation helpers
|
||||
- Integrate analytics
|
||||
|
||||
### Presentation Update Workflow
|
||||
|
||||
**⚠️ CRITICAL RULE: NEVER edit presentation_final.html directly (it's a generated file)**
|
||||
|
||||
Follow this workflow for ALL presentation updates:
|
||||
|
||||
1. **Identify what to change:**
|
||||
- Content update → Edit `assets/tabs/tab_*.html` (6 files)
|
||||
- Styling update → Edit `assets/styles.css`
|
||||
- Behavior update → Edit `assets/scripts.js`
|
||||
- Layout update → Edit `assets/presentation_template.html`
|
||||
|
||||
2. **Make changes ONLY in source files:**
|
||||
- Tab content: `assets/tabs/tab_overview.html`, `tab_requirements.html`, `tab_architecture.html`, `tab_technical_spec.html`, `tab_roadmap.html`, `tab_guides.html`
|
||||
- Styling: `assets/styles.css`
|
||||
- JavaScript: `assets/scripts.js`
|
||||
- Template: `assets/presentation_template.html`
|
||||
|
||||
3. **Rebuild presentation:**
|
||||
```bash
|
||||
cd docs/presentation
|
||||
node assets/build-presentation.js
|
||||
```
|
||||
|
||||
4. **Verify changes:**
|
||||
- Open `presentation_final.html` in browser
|
||||
- Check all tabs load correctly
|
||||
- Verify diagrams render properly
|
||||
- Test navigation between tabs
|
||||
|
||||
5. **Commit BOTH:**
|
||||
- Source files (assets/tabs/, assets/*.{css,js,html})
|
||||
- Regenerated `presentation_final.html`
|
||||
|
||||
**Why this matters:** presentation_final.html is auto-generated by combining all source files. Direct edits will be lost on next rebuild.
|
||||
|
||||
---
|
||||
|
||||
## Build Instructions
|
||||
|
||||
**Prerequisites:**
|
||||
- Project documentation in `docs/project/` (requirements.md, architecture.md, tech_stack.md, etc.)
|
||||
|
||||
**Build Process:**
|
||||
1. Run skill: `ln-115-presentation-creator`
|
||||
2. Skill reads documentation from `docs/project/`
|
||||
3. Generates HTML tabs in `assets/tabs/`
|
||||
4. Combines tabs into `presentation_final.html`
|
||||
5. Creates this README for navigation
|
||||
|
||||
**Rebuild Triggers:**
|
||||
- Updated project documentation
|
||||
- New architecture diagrams
|
||||
- Changed requirements or roadmap
|
||||
- Added new guides
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
**Last Updated:** {{LAST_UPDATED}}
|
||||
|
||||
**Update Triggers:**
|
||||
- Documentation updates in docs/project/
|
||||
- New C4 diagrams or Mermaid charts
|
||||
- Roadmap or milestone changes
|
||||
- Design system updates
|
||||
|
||||
**Verification:**
|
||||
- [ ] presentation_final.html opens without errors
|
||||
- [ ] All tabs load correctly (Overview, Requirements, Architecture, etc.)
|
||||
- [ ] Mermaid diagrams render properly
|
||||
- [ ] Navigation between tabs works
|
||||
- [ ] All links to documentation are valid
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Project Documentation](../project/README.md) - Source for presentation content
|
||||
- [Architecture Diagrams](../project/architecture.md) - C4 Model diagrams
|
||||
- [Requirements](../project/requirements.md) - Functional requirements
|
||||
|
||||
---
|
||||
|
||||
**Template Version:** 1.0.0
|
||||
**Last Updated:** {{LAST_UPDATED}}
|
||||
@@ -0,0 +1,66 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>E-Commerce Platform - Documentation</title>
|
||||
|
||||
<!-- Mermaid.js for diagrams (v11) -->
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
|
||||
<!--STYLES-->
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<!-- Header -->
|
||||
<header class="header">
|
||||
<h1>E-Commerce Platform</h1>
|
||||
<p class="subtitle">Modern Online Shopping Solution</p>
|
||||
</header>
|
||||
|
||||
<!-- Tab Navigation -->
|
||||
<nav class="tabs">
|
||||
<button class="tab-button active" data-tab="overview">Overview</button>
|
||||
<button class="tab-button" data-tab="requirements">Requirements</button>
|
||||
<button class="tab-button" data-tab="architecture">Architecture</button>
|
||||
<button class="tab-button" data-tab="technical_spec">Technical Spec</button>
|
||||
<button class="tab-button" data-tab="roadmap">Roadmap</button>
|
||||
<button class="tab-button" data-tab="guides">Guides</button>
|
||||
</nav>
|
||||
|
||||
<!-- Tab Content -->
|
||||
<main class="content">
|
||||
<div id="overview-tab" class="tab-content active">
|
||||
<!--TAB_OVERVIEW-->
|
||||
</div>
|
||||
|
||||
<div id="requirements-tab" class="tab-content">
|
||||
<!--TAB_REQUIREMENTS-->
|
||||
</div>
|
||||
|
||||
<div id="architecture-tab" class="tab-content">
|
||||
<!--TAB_ARCHITECTURE-->
|
||||
</div>
|
||||
|
||||
<div id="technical_spec-tab" class="tab-content">
|
||||
<!--TAB_TECHNICAL_SPEC-->
|
||||
</div>
|
||||
|
||||
<div id="roadmap-tab" class="tab-content">
|
||||
<!--TAB_ROADMAP-->
|
||||
</div>
|
||||
|
||||
<div id="guides-tab" class="tab-content">
|
||||
<!--TAB_GUIDES-->
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<!-- Footer -->
|
||||
<footer class="footer">
|
||||
<p>Generated on 2025-11-05 | Powered by <a href="https://github.com/anthropics/claude-code" target="_blank">Claude Code</a></p>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
<!--SCRIPTS-->
|
||||
</body>
|
||||
</html>
|
||||
124
skills/ln-115-presentation-creator/references/scripts.js
Normal file
124
skills/ln-115-presentation-creator/references/scripts.js
Normal file
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* Presentation Scripts
|
||||
*
|
||||
* Features:
|
||||
* - Tab switching with state persistence (localStorage)
|
||||
* - Collapsible sections
|
||||
* - Mermaid diagram initialization
|
||||
* - Smooth scrolling
|
||||
*/
|
||||
|
||||
document.addEventListener('DOMContentLoaded', async function() {
|
||||
// Initialize Mermaid with manual control for tab switching
|
||||
if (typeof mermaid !== 'undefined') {
|
||||
mermaid.initialize({
|
||||
startOnLoad: false, // Manual control for better tab switching
|
||||
theme: 'default',
|
||||
securityLevel: 'loose',
|
||||
logLevel: 1, // Only show errors
|
||||
flowchart: {
|
||||
useMaxWidth: true,
|
||||
htmlLabels: true
|
||||
}
|
||||
});
|
||||
|
||||
// Render diagrams in the initially active tab (only once)
|
||||
setTimeout(async () => {
|
||||
const activeTab = document.querySelector('.tab-content.active');
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
try {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true';
|
||||
} catch (err) {
|
||||
console.error('Mermaid rendering error:', err);
|
||||
}
|
||||
}
|
||||
}, 100);
|
||||
}
|
||||
|
||||
// Tab Switching
|
||||
const tabButtons = document.querySelectorAll('.tab-button');
|
||||
const tabPanes = document.querySelectorAll('.tab-content');
|
||||
|
||||
// Load saved tab from localStorage
|
||||
const savedTab = localStorage.getItem('activeTab') || 'overview';
|
||||
switchTab(savedTab);
|
||||
|
||||
tabButtons.forEach(button => {
|
||||
button.addEventListener('click', function() {
|
||||
const tabName = this.getAttribute('data-tab');
|
||||
switchTab(tabName);
|
||||
});
|
||||
});
|
||||
|
||||
async function switchTab(tabName) {
|
||||
// Update buttons
|
||||
tabButtons.forEach(btn => {
|
||||
btn.classList.remove('active');
|
||||
if (btn.getAttribute('data-tab') === tabName) {
|
||||
btn.classList.add('active');
|
||||
}
|
||||
});
|
||||
|
||||
// Update panes
|
||||
tabPanes.forEach(pane => {
|
||||
pane.classList.remove('active');
|
||||
if (pane.id === `${tabName}-tab`) {
|
||||
pane.classList.add('active');
|
||||
}
|
||||
});
|
||||
|
||||
// Save to localStorage
|
||||
localStorage.setItem('activeTab', tabName);
|
||||
|
||||
// Render Mermaid diagrams in newly activated tab (only once per tab)
|
||||
if (typeof mermaid !== 'undefined') {
|
||||
const activeTab = document.getElementById(`${tabName}-tab`);
|
||||
if (activeTab && !activeTab.dataset.mermaidRendered) {
|
||||
setTimeout(async () => {
|
||||
try {
|
||||
await mermaid.run({
|
||||
nodes: activeTab.querySelectorAll('.mermaid'),
|
||||
suppressErrors: true
|
||||
});
|
||||
activeTab.dataset.mermaidRendered = 'true';
|
||||
} catch (err) {
|
||||
console.error('Mermaid rendering error on tab switch:', err);
|
||||
}
|
||||
}, 50);
|
||||
}
|
||||
}
|
||||
|
||||
// Scroll to top
|
||||
window.scrollTo({ top: 0, behavior: 'smooth' });
|
||||
}
|
||||
|
||||
// Make switchTab available globally for inline onclick handlers
|
||||
window.switchTab = switchTab;
|
||||
|
||||
// Search functionality
|
||||
const searchInput = document.getElementById('search');
|
||||
if (searchInput) {
|
||||
searchInput.addEventListener('input', function() {
|
||||
const query = this.value.toLowerCase();
|
||||
// Basic search implementation - can be enhanced
|
||||
if (query.length > 2) {
|
||||
console.log('Searching for:', query);
|
||||
// TODO: Implement search across all tabs
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Collapsible sections (details/summary elements)
|
||||
document.querySelectorAll('details').forEach(detail => {
|
||||
detail.addEventListener('toggle', function() {
|
||||
if (this.open) {
|
||||
// Scroll into view when expanded
|
||||
this.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
778
skills/ln-115-presentation-creator/references/styles.css
Normal file
778
skills/ln-115-presentation-creator/references/styles.css
Normal file
@@ -0,0 +1,778 @@
|
||||
/* ==================== CSS Variables ==================== */
|
||||
:root {
|
||||
--primary-color: #2563eb;
|
||||
--secondary-color: #1e40af;
|
||||
--success-color: #10b981;
|
||||
--warning-color: #f59e0b;
|
||||
--danger-color: #ef4444;
|
||||
--text-color: #1f2937;
|
||||
--text-light: #6b7280;
|
||||
--bg-color: #ffffff;
|
||||
--bg-light: #f9fafb;
|
||||
--bg-dark: #f3f4f6;
|
||||
--border-color: #e5e7eb;
|
||||
--code-bg: #f3f4f6;
|
||||
--shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
|
||||
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
|
||||
}
|
||||
|
||||
/* ==================== Global Styles ==================== */
|
||||
* {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
|
||||
line-height: 1.6;
|
||||
color: var(--text-color);
|
||||
background-color: var(--bg-light);
|
||||
}
|
||||
|
||||
/* ==================== Container ==================== */
|
||||
.container {
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
/* ==================== Header ==================== */
|
||||
.header {
|
||||
text-align: center;
|
||||
padding: 40px 20px;
|
||||
background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
|
||||
color: white;
|
||||
border-radius: 8px;
|
||||
margin-bottom: 30px;
|
||||
box-shadow: var(--shadow-lg);
|
||||
}
|
||||
|
||||
.header h1 {
|
||||
font-size: 2.5rem;
|
||||
margin-bottom: 10px;
|
||||
text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
font-size: 1.1rem;
|
||||
opacity: 0.95;
|
||||
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
|
||||
}
|
||||
|
||||
/* ==================== Tabs Navigation ==================== */
|
||||
.tabs {
|
||||
display: flex;
|
||||
gap: 5px;
|
||||
margin-bottom: 20px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.tab-button {
|
||||
flex: 1;
|
||||
min-width: 120px;
|
||||
padding: 12px 20px;
|
||||
background-color: var(--bg-color);
|
||||
border: 2px solid var(--border-color);
|
||||
border-radius: 8px 8px 0 0;
|
||||
cursor: pointer;
|
||||
font-size: 1rem;
|
||||
font-weight: 500;
|
||||
color: var(--text-color);
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.tab-button:hover {
|
||||
background-color: var(--bg-dark);
|
||||
border-color: var(--primary-color);
|
||||
}
|
||||
|
||||
.tab-button.active {
|
||||
background-color: var(--primary-color);
|
||||
color: white;
|
||||
border-color: var(--primary-color);
|
||||
}
|
||||
|
||||
/* ==================== Tab Content ==================== */
|
||||
.content {
|
||||
background-color: var(--bg-color);
|
||||
border-radius: 8px;
|
||||
padding: 40px;
|
||||
box-shadow: var(--shadow);
|
||||
min-height: 500px;
|
||||
}
|
||||
|
||||
.tab-content {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.tab-content.active {
|
||||
display: block;
|
||||
animation: fadeIn 0.3s ease;
|
||||
}
|
||||
|
||||
@keyframes fadeIn {
|
||||
from { opacity: 0; transform: translateY(10px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
|
||||
/* ==================== Typography ==================== */
|
||||
h1 {
|
||||
font-size: 2rem;
|
||||
color: var(--primary-color);
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
||||
h2 {
|
||||
font-size: 1.75rem;
|
||||
color: var(--primary-color);
|
||||
margin-bottom: 20px;
|
||||
padding-bottom: 10px;
|
||||
border-bottom: 3px solid var(--primary-color);
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-size: 1.5rem;
|
||||
color: var(--secondary-color);
|
||||
margin-top: 30px;
|
||||
margin-bottom: 15px;
|
||||
}
|
||||
|
||||
h4 {
|
||||
font-size: 1.2rem;
|
||||
color: var(--text-color);
|
||||
margin-top: 20px;
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
p {
|
||||
margin-bottom: 15px;
|
||||
line-height: 1.8;
|
||||
}
|
||||
|
||||
ul, ol {
|
||||
margin-left: 30px;
|
||||
margin-bottom: 15px;
|
||||
}
|
||||
|
||||
li {
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
|
||||
section {
|
||||
margin-bottom: 40px;
|
||||
}
|
||||
|
||||
/* ==================== Code Blocks ==================== */
|
||||
code {
|
||||
background-color: var(--code-bg);
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-family: "Monaco", "Courier New", monospace;
|
||||
font-size: 0.9em;
|
||||
color: var(--danger-color);
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: var(--code-bg);
|
||||
padding: 15px;
|
||||
border-radius: 8px;
|
||||
overflow-x: auto;
|
||||
margin-bottom: 20px;
|
||||
border-left: 4px solid var(--primary-color);
|
||||
}
|
||||
|
||||
pre code {
|
||||
background-color: transparent;
|
||||
padding: 0;
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
/* ==================== Tables ==================== */
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin-bottom: 20px;
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
thead {
|
||||
background-color: var(--primary-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
th, td {
|
||||
padding: 12px;
|
||||
text-align: left;
|
||||
border-bottom: 1px solid var(--border-color);
|
||||
}
|
||||
|
||||
tbody tr:hover {
|
||||
background-color: var(--bg-light);
|
||||
}
|
||||
|
||||
/* ==================== Cards ==================== */
|
||||
.card {
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 8px;
|
||||
padding: 20px;
|
||||
margin-bottom: 20px;
|
||||
box-shadow: var(--shadow);
|
||||
border-left: 4px solid var(--primary-color);
|
||||
}
|
||||
|
||||
.card h4 {
|
||||
margin-top: 0;
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
/* ==================== Badges ==================== */
|
||||
.badge {
|
||||
display: inline-block;
|
||||
padding: 4px 10px;
|
||||
border-radius: 12px;
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
margin-right: 5px;
|
||||
}
|
||||
|
||||
.badge-success {
|
||||
background-color: var(--success-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.badge-warning {
|
||||
background-color: var(--warning-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.badge-danger {
|
||||
background-color: var(--danger-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.badge-primary {
|
||||
background-color: var(--primary-color);
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* ==================== Overview Tab Components ==================== */
|
||||
/* Role-based Navigation Cards */
|
||||
.role-navigation {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.role-cards {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
|
||||
gap: 20px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.role-card {
|
||||
padding: 20px;
|
||||
background-color: var(--bg-color);
|
||||
border: 2px solid var(--border-color);
|
||||
border-radius: 8px;
|
||||
cursor: pointer;
|
||||
transition: all 0.3s ease;
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.role-card:hover {
|
||||
border-color: var(--primary-color);
|
||||
box-shadow: var(--shadow-lg);
|
||||
transform: translateY(-2px);
|
||||
}
|
||||
|
||||
.role-card h3 {
|
||||
font-size: 1.1rem;
|
||||
margin-top: 0;
|
||||
margin-bottom: 10px;
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.role-card p {
|
||||
font-size: 0.9rem;
|
||||
color: var(--text-light);
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* Tech Stack Badges */
|
||||
.tech-stack-section {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.tech-badges {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 12px;
|
||||
margin-top: 15px;
|
||||
}
|
||||
|
||||
.tech-badge {
|
||||
padding: 8px 16px;
|
||||
background-color: var(--bg-light);
|
||||
border: 1px solid var(--border-color);
|
||||
border-radius: 6px;
|
||||
font-size: 0.9rem;
|
||||
font-weight: 500;
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
/* Quick Stats */
|
||||
.quick-stats {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.stats-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
||||
gap: 20px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.stat-card {
|
||||
padding: 20px;
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 8px;
|
||||
text-align: center;
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.stat-card h3 {
|
||||
font-size: 2rem;
|
||||
color: var(--primary-color);
|
||||
margin: 0 0 5px 0;
|
||||
}
|
||||
|
||||
.stat-card p {
|
||||
font-size: 0.9rem;
|
||||
color: var(--text-light);
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* Quick Links */
|
||||
/* ==================== Overview Tab - New Components ==================== */
|
||||
/* Stakeholders Section */
|
||||
.stakeholders-section {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.stakeholders-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
||||
gap: 20px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.stakeholder-card {
|
||||
padding: 20px;
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 8px;
|
||||
text-align: center;
|
||||
box-shadow: var(--shadow);
|
||||
border-top: 4px solid var(--primary-color);
|
||||
}
|
||||
|
||||
.stakeholder-card h3 {
|
||||
font-size: 1rem;
|
||||
color: var(--text-color);
|
||||
margin: 0 0 8px 0;
|
||||
}
|
||||
|
||||
.stakeholder-card p {
|
||||
font-size: 0.9rem;
|
||||
margin: 3px 0;
|
||||
}
|
||||
|
||||
.stakeholder-card .role {
|
||||
color: var(--text-light);
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
|
||||
/* Navigation Guide */
|
||||
.navigation-guide {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.guide-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
|
||||
gap: 20px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.guide-card {
|
||||
padding: 20px;
|
||||
background-color: var(--bg-light);
|
||||
border: 2px solid var(--border-color);
|
||||
border-radius: 8px;
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.guide-card:hover {
|
||||
border-color: var(--primary-color);
|
||||
box-shadow: var(--shadow-lg);
|
||||
transform: translateY(-2px);
|
||||
}
|
||||
|
||||
.guide-card h3 {
|
||||
font-size: 1.1rem;
|
||||
color: var(--primary-color);
|
||||
margin: 0 0 10px 0;
|
||||
}
|
||||
|
||||
.guide-card p {
|
||||
font-size: 0.9rem;
|
||||
color: var(--text-color);
|
||||
margin: 8px 0;
|
||||
}
|
||||
|
||||
.guide-card .audience {
|
||||
font-size: 0.85rem;
|
||||
color: var(--text-light);
|
||||
font-style: italic;
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
/* ==================== Roadmap Tab Components ==================== */
|
||||
/* Roadmap Intro */
|
||||
.roadmap-intro {
|
||||
background-color: var(--bg-light);
|
||||
padding: 20px;
|
||||
border-radius: 8px;
|
||||
border-left: 4px solid var(--primary-color);
|
||||
margin-bottom: 30px;
|
||||
font-size: 1rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
/* Kanban Board - 5 columns layout */
|
||||
/* ==================== Epics List (Roadmap) ==================== */
|
||||
.epics-list {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 24px;
|
||||
margin: 30px 0;
|
||||
}
|
||||
|
||||
.epic-item {
|
||||
background-color: var(--bg-color);
|
||||
border: 1px solid var(--border-color);
|
||||
border-radius: 8px;
|
||||
padding: 24px;
|
||||
box-shadow: var(--shadow);
|
||||
transition: box-shadow 0.3s ease;
|
||||
}
|
||||
|
||||
.epic-item:hover {
|
||||
box-shadow: var(--shadow-lg);
|
||||
}
|
||||
|
||||
.epic-header {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.epic-header h3 {
|
||||
margin: 0;
|
||||
font-size: 1.4rem;
|
||||
color: var(--text-color);
|
||||
}
|
||||
|
||||
.epic-description {
|
||||
color: var(--text-light);
|
||||
margin-bottom: 16px;
|
||||
font-size: 1rem;
|
||||
}
|
||||
|
||||
.epic-details {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 20px;
|
||||
margin-bottom: 16px;
|
||||
padding: 16px;
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 6px;
|
||||
}
|
||||
|
||||
.epic-scope h4 {
|
||||
font-size: 0.9rem;
|
||||
text-transform: uppercase;
|
||||
color: var(--text-light);
|
||||
margin-bottom: 8px;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.epic-scope ul {
|
||||
margin: 0;
|
||||
padding-left: 20px;
|
||||
}
|
||||
|
||||
.epic-scope li {
|
||||
font-size: 0.9rem;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.epic-meta {
|
||||
border-top: 1px solid var(--border-color);
|
||||
padding-top: 12px;
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.epic-meta p {
|
||||
margin: 4px 0;
|
||||
font-size: 0.9rem;
|
||||
color: var(--text-light);
|
||||
}
|
||||
|
||||
/* Epic Status Badges */
|
||||
.epic-status {
|
||||
padding: 6px 12px;
|
||||
border-radius: 12px;
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.status-done {
|
||||
background-color: #d1fae5;
|
||||
color: #065f46;
|
||||
}
|
||||
|
||||
.status-progress {
|
||||
background-color: #dbeafe;
|
||||
color: #1e40af;
|
||||
}
|
||||
|
||||
.status-todo {
|
||||
background-color: #f3f4f6;
|
||||
color: #4b5563;
|
||||
}
|
||||
|
||||
.status-backlog {
|
||||
background-color: #fef3c7;
|
||||
color: #92400e;
|
||||
}
|
||||
|
||||
/* Out of Scope Items */
|
||||
.out-of-scope-items {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.out-of-scope-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
|
||||
gap: 20px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.out-of-scope-card {
|
||||
background-color: #fef2f2;
|
||||
border: 2px solid #fca5a5;
|
||||
border-radius: 8px;
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.out-of-scope-card h4 {
|
||||
color: #dc2626;
|
||||
margin: 0 0 8px 0;
|
||||
}
|
||||
|
||||
.scope-reason {
|
||||
font-size: 0.85rem;
|
||||
color: var(--text-light);
|
||||
margin-top: 8px;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
/* Roadmap Legend */
|
||||
.roadmap-legend {
|
||||
margin-top: 32px;
|
||||
padding: 16px;
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 8px;
|
||||
}
|
||||
|
||||
.status-badges {
|
||||
display: flex;
|
||||
gap: 12px;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
font-size: 0.9rem;
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.progress-fill {
|
||||
background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
|
||||
height: 100%;
|
||||
border-radius: 4px;
|
||||
transition: width 0.5s ease;
|
||||
}
|
||||
|
||||
/* Roadmap Legend */
|
||||
.roadmap-legend {
|
||||
margin: 40px 0;
|
||||
background-color: var(--bg-light);
|
||||
padding: 20px;
|
||||
border-radius: 8px;
|
||||
border: 1px solid var(--border-color);
|
||||
}
|
||||
|
||||
.roadmap-legend h3 {
|
||||
margin-top: 0;
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
.roadmap-legend ul {
|
||||
margin-left: 20px;
|
||||
}
|
||||
|
||||
.roadmap-legend li {
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
/* ==================== Requirements Tab Components ==================== */
|
||||
/* Priority Badges */
|
||||
.priority-must {
|
||||
background-color: #fee2e2;
|
||||
color: #991b1b;
|
||||
padding: 4px 8px;
|
||||
border-radius: 4px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 700;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
/* ADR Accordion */
|
||||
.adr-section {
|
||||
margin: 40px 0;
|
||||
}
|
||||
|
||||
.adr-group {
|
||||
margin: 30px 0;
|
||||
}
|
||||
|
||||
.adr-group h3 {
|
||||
margin-top: 40px;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
|
||||
details.adr-item {
|
||||
margin-bottom: 15px;
|
||||
padding: 15px;
|
||||
background-color: var(--bg-light);
|
||||
border: 1px solid var(--border-color);
|
||||
border-radius: 8px;
|
||||
}
|
||||
|
||||
details.adr-item summary {
|
||||
cursor: pointer;
|
||||
font-weight: 600;
|
||||
color: var(--primary-color);
|
||||
font-size: 1.1rem;
|
||||
}
|
||||
|
||||
details.adr-item summary:hover {
|
||||
color: var(--secondary-color);
|
||||
}
|
||||
|
||||
details.adr-item[open] summary {
|
||||
margin-bottom: 15px;
|
||||
padding-bottom: 15px;
|
||||
border-bottom: 2px solid var(--border-color);
|
||||
}
|
||||
|
||||
/* Collapsible Sections */
|
||||
details {
|
||||
margin-bottom: 15px;
|
||||
}
|
||||
|
||||
summary {
|
||||
cursor: pointer;
|
||||
font-weight: 600;
|
||||
padding: 10px;
|
||||
background-color: var(--bg-light);
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
summary:hover {
|
||||
background-color: var(--bg-dark);
|
||||
}
|
||||
|
||||
/* ==================== Mermaid Diagrams ==================== */
|
||||
.mermaid {
|
||||
background-color: white;
|
||||
padding: 20px;
|
||||
border-radius: 8px;
|
||||
margin: 20px 0;
|
||||
text-align: center;
|
||||
border: 1px solid var(--border-color);
|
||||
}
|
||||
|
||||
/* ==================== Blockquotes ==================== */
|
||||
blockquote {
|
||||
margin: 20px 0;
|
||||
padding: 15px 20px;
|
||||
border-left: 4px solid var(--primary-color);
|
||||
background-color: var(--bg-light);
|
||||
font-style: italic;
|
||||
color: var(--text-light);
|
||||
}
|
||||
|
||||
/* ==================== Footer ==================== */
|
||||
.footer {
|
||||
text-align: center;
|
||||
padding: 20px;
|
||||
margin-top: 40px;
|
||||
color: var(--text-light);
|
||||
font-size: 0.9rem;
|
||||
border-top: 2px solid var(--border-color);
|
||||
}
|
||||
|
||||
/* ==================== Responsive Design ==================== */
|
||||
@media (max-width: 768px) {
|
||||
.header h1 {
|
||||
font-size: 1.8rem;
|
||||
}
|
||||
|
||||
.tabs {
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
.tab-button {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.content {
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.epic-details {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.out-of-scope-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.role-cards {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.stats-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
table {
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
|
||||
th, td {
|
||||
padding: 8px;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,177 @@
|
||||
<!-- SCOPE: System Structure Visualization (Diagrams Only) -->
|
||||
<!-- INCLUDES: C4 diagrams (Context/Container/Component), Deployment diagram, brief captions -->
|
||||
<!-- EXCLUDES: Decision rationale → ADRs, Requirements → Requirements tab, API details → Technical Spec, Non-Functional Requirements (forbidden; keep quality topics as architecture narrative only) -->
|
||||
|
||||
<h2>Architecture</h2>
|
||||
|
||||
<!-- PLACEHOLDER: {{C4_CONTEXT}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="c4-diagrams">
|
||||
<h3>System Context (C4 Level 1)</h3>
|
||||
<p>High-level view of the e-commerce platform and its external dependencies.</p>
|
||||
<div class="mermaid">
|
||||
graph TD
|
||||
Customer[Customer]
|
||||
Admin[Administrator]
|
||||
PaymentGateway[Payment Gateway<br/>Stripe]
|
||||
EmailService[Email Service<br/>SendGrid]
|
||||
|
||||
System[E-Commerce Platform]
|
||||
|
||||
Customer -->|Browse products,<br/>Place orders| System
|
||||
Admin -->|Manage products,<br/>View analytics| System
|
||||
System -->|Process payments| PaymentGateway
|
||||
System -->|Send notifications| EmailService
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{C4_CONTAINER}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<h3>Container Diagram (C4 Level 2)</h3>
|
||||
<p>Containers within the e-commerce platform showing technologies and communication.</p>
|
||||
<div class="mermaid">
|
||||
graph TD
|
||||
Customer[Customer<br/>Web Browser]
|
||||
Admin[Administrator<br/>Web Browser]
|
||||
|
||||
WebApp[Web Application<br/>React 18 SPA]
|
||||
API[REST API<br/>Node.js + Express]
|
||||
Database[(Database<br/>PostgreSQL 15)]
|
||||
Cache[(Cache<br/>Redis)]
|
||||
|
||||
Customer -->|HTTPS| WebApp
|
||||
Admin -->|HTTPS| WebApp
|
||||
WebApp -->|JSON/HTTPS| API
|
||||
API -->|SQL| Database
|
||||
API -->|Cache queries| Cache
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{C4_COMPONENT}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<h3>Component Diagram (C4 Level 3) - Optional for Technical Audiences</h3>
|
||||
<p>Components within the REST API container showing internal structure.</p>
|
||||
<div class="mermaid">
|
||||
graph TD
|
||||
API[REST API Container]
|
||||
|
||||
AuthController[Authentication<br/>Controller]
|
||||
ProductController[Product Catalog<br/>Controller]
|
||||
CartController[Shopping Cart<br/>Controller]
|
||||
OrderController[Order<br/>Controller]
|
||||
|
||||
AuthService[Auth Service]
|
||||
ProductService[Product Service]
|
||||
CartService[Cart Service]
|
||||
OrderService[Order Service]
|
||||
|
||||
ProductRepo[Product<br/>Repository]
|
||||
UserRepo[User<br/>Repository]
|
||||
CartRepo[Cart<br/>Repository]
|
||||
OrderRepo[Order<br/>Repository]
|
||||
|
||||
Database[(PostgreSQL)]
|
||||
Cache[(Redis)]
|
||||
|
||||
ProductController --> ProductService
|
||||
CartController --> CartService
|
||||
OrderController --> OrderService
|
||||
AuthController --> AuthService
|
||||
|
||||
ProductService --> ProductRepo
|
||||
CartService --> CartRepo
|
||||
OrderService --> OrderRepo
|
||||
AuthService --> UserRepo
|
||||
|
||||
ProductRepo --> Database
|
||||
UserRepo --> Database
|
||||
CartRepo --> Cache
|
||||
OrderRepo --> Database
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{DEPLOYMENT_DIAGRAM}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<h3>Deployment Diagram</h3>
|
||||
<p>Infrastructure and deployment architecture on AWS.</p>
|
||||
<div class="mermaid">
|
||||
graph TD
|
||||
subgraph "AWS Cloud"
|
||||
subgraph "Public Subnet"
|
||||
ALB[Application Load<br/>Balancer]
|
||||
CloudFront[CloudFront CDN]
|
||||
end
|
||||
|
||||
subgraph "Private Subnet"
|
||||
ECS1[ECS Container 1<br/>Node.js API]
|
||||
ECS2[ECS Container 2<br/>Node.js API]
|
||||
|
||||
RDS[(RDS PostgreSQL<br/>Primary)]
|
||||
RDSReplica[(RDS PostgreSQL<br/>Read Replica)]
|
||||
|
||||
ElastiCache[(ElastiCache<br/>Redis)]
|
||||
end
|
||||
|
||||
subgraph "Storage"
|
||||
S3[S3 Bucket<br/>Static Assets]
|
||||
end
|
||||
end
|
||||
|
||||
CloudFront --> S3
|
||||
ALB --> ECS1
|
||||
ALB --> ECS2
|
||||
ECS1 --> RDS
|
||||
ECS2 --> RDS
|
||||
ECS1 --> RDSReplica
|
||||
ECS2 --> RDSReplica
|
||||
ECS1 --> ElastiCache
|
||||
ECS2 --> ElastiCache
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{ARCHITECTURE_NOTES}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="architecture-notes">
|
||||
<h3>Key Architecture Highlights</h3>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Aspect</th>
|
||||
<th>Approach</th>
|
||||
<th>Rationale</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Architecture Pattern</td>
|
||||
<td>Modular Monolith</td>
|
||||
<td>Clear domain boundaries (Auth, Catalog, Cart, Orders) - see ADR-001 in Requirements</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>API Design</td>
|
||||
<td>Stateless API</td>
|
||||
<td>Enables horizontal scaling without session affinity</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Database Strategy</td>
|
||||
<td>PostgreSQL with read replicas</td>
|
||||
<td>ACID transactions + scalability through read replicas</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Caching</td>
|
||||
<td>Redis</td>
|
||||
<td>Session/cart data and frequently accessed product catalog</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Infrastructure</td>
|
||||
<td>Docker containers</td>
|
||||
<td>Cloud-native orchestration with Kubernetes</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p><em>For detailed quality attributes (Performance, Security, Scalability, Maintainability), see requirements.md in docs/project/.</em></p>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
@@ -0,0 +1,198 @@
|
||||
<!-- SCOPE: How-To Guides (Practical Task Instructions) -->
|
||||
<!-- INCLUDES: Step-by-step guides (Installation, Development, Deployment, Integration), Prerequisites, Verification steps, Troubleshooting, Best practices -->
|
||||
<!-- EXCLUDES: Conceptual explanations → Requirements/Architecture, API reference → Technical Spec, What/Why → Requirements, System design → Architecture, Work planning → Roadmap -->
|
||||
|
||||
<h2>Guides & Resources</h2>
|
||||
|
||||
<!-- PLACEHOLDER: {{GETTING_STARTED}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="getting-started">
|
||||
<h3>Getting Started</h3>
|
||||
|
||||
<h4>Prerequisites</h4>
|
||||
<ul>
|
||||
<li>Node.js 20.x or higher</li>
|
||||
<li>PostgreSQL 15.x</li>
|
||||
<li>Redis 7.x (optional for development)</li>
|
||||
<li>Docker (optional)</li>
|
||||
</ul>
|
||||
|
||||
<h4>Installation</h4>
|
||||
<pre><code>git clone https://github.com/example/ecommerce-platform.git
|
||||
cd ecommerce-platform
|
||||
npm install
|
||||
cp .env.example .env
|
||||
# Edit .env with your database credentials
|
||||
npm run db:migrate
|
||||
npm run dev</code></pre>
|
||||
|
||||
<h4>Verification</h4>
|
||||
<p>After starting the server, verify installation:</p>
|
||||
<ul>
|
||||
<li>✅ Server running at <code>http://localhost:3000</code></li>
|
||||
<li>✅ API health check: <code>curl http://localhost:3000/api/health</code></li>
|
||||
<li>✅ Database migrations applied: <code>npm run db:status</code></li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{HOW_TO_GUIDES}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="how-to-guides">
|
||||
<h3>How-To Guides</h3>
|
||||
|
||||
<div class="card">
|
||||
<h4>How to Add a New Product</h4>
|
||||
<ol>
|
||||
<li>Login as admin: <code>POST /api/auth/login</code> with admin credentials</li>
|
||||
<li>Get JWT token from response</li>
|
||||
<li>Create product:
|
||||
<pre><code>curl -X POST http://localhost:3000/api/products \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Product Name",
|
||||
"description": "Product Description",
|
||||
"price": 29.99,
|
||||
"stock_quantity": 100,
|
||||
"category": "Electronics"
|
||||
}'</code></pre>
|
||||
</li>
|
||||
<li>Verify product created: <code>GET /api/products/:id</code></li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h4>How to Test API Endpoints</h4>
|
||||
<ol>
|
||||
<li>Start development server: <code>npm run dev</code></li>
|
||||
<li>Run tests:
|
||||
<ul>
|
||||
<li>All tests: <code>npm test</code></li>
|
||||
<li>E2E tests only: <code>npm run test:e2e</code></li>
|
||||
<li>Integration tests: <code>npm run test:integration</code></li>
|
||||
<li>Unit tests: <code>npm run test:unit</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>View coverage report: <code>npm run test:coverage</code></li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h4>How to Deploy to Production</h4>
|
||||
<ol>
|
||||
<li>Build Docker image: <code>docker build -t ecommerce-api .</code></li>
|
||||
<li>Push to registry: <code>docker push ecommerce-api:latest</code></li>
|
||||
<li>Update ECS task definition with new image</li>
|
||||
<li>Deploy via GitHub Actions (automatic on merge to main)</li>
|
||||
<li>Verify deployment: Check CloudWatch logs for startup</li>
|
||||
</ol>
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{BEST_PRACTICES}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="best-practices">
|
||||
<h3>Best Practices</h3>
|
||||
|
||||
<h4>Code Style</h4>
|
||||
<ul>
|
||||
<li>Follow KISS/YAGNI/DRY principles</li>
|
||||
<li>Use TypeScript for type safety</li>
|
||||
<li>Keep functions small and focused (< 30 lines)</li>
|
||||
<li>Use meaningful variable names (no single letters except loops)</li>
|
||||
</ul>
|
||||
|
||||
<h4>Testing Approach</h4>
|
||||
<ul>
|
||||
<li>Follow Risk-Based Testing (Priority ≥ 15 scenarios MUST be tested)</li>
|
||||
<li>E2E tests (2-5 per Story): Critical user flows</li>
|
||||
<li>Integration tests (3-8 per Story): API endpoints</li>
|
||||
<li>Unit tests (5-15 per Story): Business logic only</li>
|
||||
<li>Test OUR code, not frameworks (Express already tested)</li>
|
||||
</ul>
|
||||
|
||||
<h4>Design Patterns</h4>
|
||||
<ul>
|
||||
<li>Layered architecture: Controller → Service → Repository</li>
|
||||
<li>Dependency Injection for testability</li>
|
||||
<li>Repository pattern for database access</li>
|
||||
<li>DTO (Data Transfer Objects) for API requests/responses</li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{TROUBLESHOOTING}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="troubleshooting">
|
||||
<h3>Troubleshooting</h3>
|
||||
|
||||
<h4>Database Connection Errors</h4>
|
||||
<p><strong>Problem:</strong> "Unable to connect to PostgreSQL"</p>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<ul>
|
||||
<li>Check PostgreSQL is running: <code>pg_isready</code></li>
|
||||
<li>Verify .env credentials match database</li>
|
||||
<li>Check firewall allows port 5432</li>
|
||||
</ul>
|
||||
|
||||
<h4>Port Already in Use</h4>
|
||||
<p><strong>Problem:</strong> "Port 3000 is already in use"</p>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<ul>
|
||||
<li>Change PORT in .env to different port (e.g., 3001)</li>
|
||||
<li>Or kill process using port: <code>lsof -ti:3000 | xargs kill</code></li>
|
||||
</ul>
|
||||
|
||||
<h4>JWT Token Expired</h4>
|
||||
<p><strong>Problem:</strong> "401 Unauthorized - Token expired"</p>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<ul>
|
||||
<li>Use refresh token: <code>POST /api/auth/refresh</code> with refresh token</li>
|
||||
<li>Get new access token from response</li>
|
||||
<li>Tokens expire after 15 minutes for security</li>
|
||||
</ul>
|
||||
|
||||
<h4>Tests Failing Randomly</h4>
|
||||
<p><strong>Problem:</strong> Tests pass locally but fail in CI</p>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<ul>
|
||||
<li>Check test isolation (no shared state between tests)</li>
|
||||
<li>Use transactions in tests (rollback after each test)</li>
|
||||
<li>Seed database with consistent test data</li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{CONTRIBUTING}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="contributing">
|
||||
<h3>Contributing Guidelines</h3>
|
||||
<ol>
|
||||
<li><strong>Fork</strong> the repository</li>
|
||||
<li><strong>Create branch:</strong> <code>git checkout -b feature/your-feature</code></li>
|
||||
<li><strong>Write code</strong> following style guide</li>
|
||||
<li><strong>Write tests:</strong> All new code must have tests (85%+ coverage)</li>
|
||||
<li><strong>Run tests:</strong> <code>npm test</code> (all must pass)</li>
|
||||
<li><strong>Commit:</strong> <code>git commit -m "Add your feature"</code></li>
|
||||
<li><strong>Push:</strong> <code>git push origin feature/your-feature</code></li>
|
||||
<li><strong>Submit PR</strong> with description of changes</li>
|
||||
</ol>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{EXTERNAL_RESOURCES}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="external-resources">
|
||||
<h3>External Resources</h3>
|
||||
<ul>
|
||||
<li><a href="https://nodejs.org/docs" target="_blank">Node.js Documentation</a></li>
|
||||
<li><a href="https://www.postgresql.org/docs/" target="_blank">PostgreSQL Documentation</a></li>
|
||||
<li><a href="https://redis.io/docs/" target="_blank">Redis Documentation</a></li>
|
||||
<li><a href="https://expressjs.com/" target="_blank">Express.js Guide</a></li>
|
||||
<li><a href="https://react.dev/" target="_blank">React Documentation</a></li>
|
||||
<li><a href="https://www.typescriptlang.org/docs/" target="_blank">TypeScript Handbook</a></li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
@@ -0,0 +1,127 @@
|
||||
<!-- SCOPE: Project Overview & Navigation -->
|
||||
<!-- INCLUDES: Problem statement, solution approach, business value, tech stack (list only), key stakeholders, navigation guide, quick stats -->
|
||||
<!-- EXCLUDES: Detailed goals → Requirements, Architecture decisions → ADRs, Diagrams → Architecture, API details → Technical Spec, Work order → Roadmap, How-to → Guides -->
|
||||
|
||||
<!-- PLACEHOLDER: {{PROJECT_SUMMARY}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="project-summary">
|
||||
<h2>Project Summary</h2>
|
||||
|
||||
<h3>The Problem</h3>
|
||||
<p>Traditional e-commerce platforms struggle with scalability during peak traffic, complex payment integrations, and fragmented inventory management across multiple channels. Businesses need a unified platform that handles high concurrent loads while maintaining data consistency and security.</p>
|
||||
|
||||
<h3>Our Solution</h3>
|
||||
<p>An enterprise-grade e-commerce platform built with modern web technologies and modular architecture. The system provides seamless online shopping experiences through stateless API design, robust payment processing with PCI DSS compliance, real-time inventory synchronization, and comprehensive customer analytics.</p>
|
||||
|
||||
<h3>Business Value</h3>
|
||||
<ul>
|
||||
<li><strong>Scalability:</strong> Support 10,000+ concurrent users with horizontal scaling</li>
|
||||
<li><strong>Reliability:</strong> 99.9% uptime SLA with automated failover</li>
|
||||
<li><strong>Speed to Market:</strong> Modular architecture enables rapid feature delivery</li>
|
||||
<li><strong>Cost Efficiency:</strong> Optimized infrastructure reduces operational costs by 30%</li>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{TECH_STACK}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="tech-stack-section">
|
||||
<h2>Technology Stack</h2>
|
||||
<div class="tech-badges">
|
||||
<span class="tech-badge">React 18</span>
|
||||
<span class="tech-badge">Node.js</span>
|
||||
<span class="tech-badge">PostgreSQL</span>
|
||||
<span class="tech-badge">Redis</span>
|
||||
<span class="tech-badge">Docker</span>
|
||||
<span class="tech-badge">TypeScript</span>
|
||||
</div>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{STAKEHOLDERS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="stakeholders-section">
|
||||
<h2>Key Stakeholders</h2>
|
||||
<div class="stakeholders-grid">
|
||||
<div class="stakeholder-card">
|
||||
<h3>Project Owner</h3>
|
||||
<p>John Smith</p>
|
||||
<p class="role">Business Sponsor</p>
|
||||
</div>
|
||||
<div class="stakeholder-card">
|
||||
<h3>Lead Architect</h3>
|
||||
<p>Jane Doe</p>
|
||||
<p class="role">Technical Lead</p>
|
||||
</div>
|
||||
<div class="stakeholder-card">
|
||||
<h3>Development Lead</h3>
|
||||
<p>Alex Johnson</p>
|
||||
<p class="role">Engineering Manager</p>
|
||||
</div>
|
||||
<div class="stakeholder-card">
|
||||
<h3>Product Manager</h3>
|
||||
<p>Sarah Williams</p>
|
||||
<p class="role">Product Strategy</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{QUICK_FACTS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="quick-stats">
|
||||
<h2>Project Quick Facts</h2>
|
||||
<div class="stats-grid">
|
||||
<div class="stat-card">
|
||||
<h3>In Progress</h3>
|
||||
<p>Project Status</p>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<h3>7</h3>
|
||||
<p>Total Epics</p>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<h3>Cloud</h3>
|
||||
<p>Deployment Model</p>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<h3>Web + Mobile</h3>
|
||||
<p>Target Platforms</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{NAVIGATION_GUIDE}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="navigation-guide">
|
||||
<h2>Documentation Guide</h2>
|
||||
<div class="guide-grid">
|
||||
<div class="guide-card">
|
||||
<h3>📋 Requirements</h3>
|
||||
<p>What we're building and why - functional requirements only and architecture decisions (ADRs); Non-Functional Requirements are not produced</p>
|
||||
<p class="audience"><strong>For:</strong> Product Owners, Business Analysts, Architects</p>
|
||||
</div>
|
||||
<div class="guide-card">
|
||||
<h3>🏗️ Architecture</h3>
|
||||
<p>How the system is designed - C4 diagrams showing context, containers, components, and deployment infrastructure</p>
|
||||
<p class="audience"><strong>For:</strong> Architects, Technical Leads, DevOps Engineers</p>
|
||||
</div>
|
||||
<div class="guide-card">
|
||||
<h3>⚙️ Technical Spec</h3>
|
||||
<p>How to interact with the system - API documentation, data models, schemas, and infrastructure configuration</p>
|
||||
<p class="audience"><strong>For:</strong> Developers, QA Engineers, Integration Teams</p>
|
||||
</div>
|
||||
<div class="guide-card">
|
||||
<h3>🗺️ Roadmap</h3>
|
||||
<p>Work order and scope boundaries - Kanban board showing epic progress, dependencies, and what's in/out of scope</p>
|
||||
<p class="audience"><strong>For:</strong> Stakeholders, Project Managers, Executives</p>
|
||||
</div>
|
||||
<div class="guide-card">
|
||||
<h3>📚 Guides</h3>
|
||||
<p>How to perform practical tasks - step-by-step guides for installation, development, deployment, and integration</p>
|
||||
<p class="audience"><strong>For:</strong> Developers, DevOps Engineers, New Team Members</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
@@ -0,0 +1,210 @@
|
||||
<!-- SCOPE: Functional Requirements & Architecture Decisions -->
|
||||
<!-- INCLUDES: FRs (what we build), ADRs (why we decided), Success criteria -->
|
||||
<!-- EXCLUDES: Non-Functional Requirements (forbidden), Business context → Overview, System structure → Architecture, API contracts → Technical Spec, Implementation steps → Guides -->
|
||||
|
||||
<h2>Requirements</h2>
|
||||
|
||||
<!-- PLACEHOLDER: {{FUNCTIONAL_REQUIREMENTS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="functional-requirements">
|
||||
<h3>Functional Requirements</h3>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>ID</th>
|
||||
<th>Priority</th>
|
||||
<th>Requirement</th>
|
||||
<th>Acceptance Criteria</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>FR-AUTH-001</td>
|
||||
<td><span class="priority-must">MUST</span></td>
|
||||
<td><strong>User Registration and Login</strong><br>
|
||||
Users must be able to register with email/password and login to access personalized features</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>Email validation (RFC 5322 compliant)</li>
|
||||
<li>Password strength requirements (min 8 chars, uppercase, lowercase, number)</li>
|
||||
<li>JWT token-based authentication</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FR-CATALOG-001</td>
|
||||
<td><span class="priority-must">MUST</span></td>
|
||||
<td><strong>Product Catalog Display</strong><br>
|
||||
System must display product catalog with search, filters, and pagination</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>Full-text search across product names and descriptions</li>
|
||||
<li>Filter by category, price range, availability</li>
|
||||
<li>Paginate results (20 items per page)</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FR-CART-001</td>
|
||||
<td><span class="priority-must">MUST</span></td>
|
||||
<td><strong>Shopping Cart Management</strong><br>
|
||||
Users must be able to add/remove products to/from cart</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>Add product with quantity selection</li>
|
||||
<li>Update quantities in cart</li>
|
||||
<li>Remove items from cart</li>
|
||||
<li>Cart persists across sessions (logged-in users)</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{ADR_STRATEGIC}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="adr-section">
|
||||
<h3>📋 Architecture Decision Records</h3>
|
||||
|
||||
<div class="adr-group">
|
||||
<h4>🎯 Strategic Decisions</h4>
|
||||
|
||||
<details class="adr-item">
|
||||
<summary>ADR-001: Microservices vs Monolith Architecture</summary>
|
||||
<p><strong>Date:</strong> 2025-09-15 | <strong>Status:</strong> Accepted | <strong>Category:</strong> Strategic</p>
|
||||
|
||||
<h4>Context</h4>
|
||||
<p>Need to choose architecture pattern for e-commerce platform considering team size, scaling requirements, and deployment complexity.</p>
|
||||
|
||||
<h4>Decision</h4>
|
||||
<p>Use <strong>modular monolith</strong> architecture with clear domain boundaries.</p>
|
||||
|
||||
<h4>Rationale</h4>
|
||||
<ul>
|
||||
<li>Small team (5 developers) - microservices overhead too high</li>
|
||||
<li>Faster time to market with simplified deployment</li>
|
||||
<li>Clear module boundaries allow future microservices extraction</li>
|
||||
</ul>
|
||||
|
||||
<h4>Alternatives Considered</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Alternative</th>
|
||||
<th>Pros</th>
|
||||
<th>Cons</th>
|
||||
<th>Rejection Reason</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Microservices</td>
|
||||
<td>Independent scaling, technology diversity</td>
|
||||
<td>Operational complexity, team overhead</td>
|
||||
<td>Team too small, premature optimization</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Traditional monolith</td>
|
||||
<td>Simplest to build</td>
|
||||
<td>Difficult to scale, tight coupling</td>
|
||||
<td>No clear boundaries for future evolution</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Consequences</h4>
|
||||
<p><strong>Positive:</strong></p>
|
||||
<ul>
|
||||
<li>Faster development and deployment</li>
|
||||
<li>Easier testing and debugging</li>
|
||||
<li>Lower infrastructure costs</li>
|
||||
</ul>
|
||||
<p><strong>Negative:</strong></p>
|
||||
<ul>
|
||||
<li>Cannot scale individual modules independently</li>
|
||||
<li>Requires discipline to maintain module boundaries</li>
|
||||
</ul>
|
||||
</details>
|
||||
</div>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{ADR_TECHNICAL}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<div class="adr-group">
|
||||
<h4>🔧 Technical Decisions</h4>
|
||||
|
||||
<details class="adr-item">
|
||||
<summary>ADR-002: Database Choice - PostgreSQL vs MongoDB</summary>
|
||||
<p><strong>Date:</strong> 2025-09-18 | <strong>Status:</strong> Accepted | <strong>Category:</strong> Technical</p>
|
||||
|
||||
<h4>Context</h4>
|
||||
<p>Need to select database for e-commerce transactional data considering ACID requirements, scalability, and query complexity.</p>
|
||||
|
||||
<h4>Decision</h4>
|
||||
<p>Use <strong>PostgreSQL 15.x</strong> as primary database.</p>
|
||||
|
||||
<h4>Rationale</h4>
|
||||
<ul>
|
||||
<li>Strong ACID guarantees for transactions (orders, payments)</li>
|
||||
<li>JSON support for flexible product attributes</li>
|
||||
<li>Excellent performance for complex queries</li>
|
||||
</ul>
|
||||
|
||||
<h4>Alternatives Considered</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Alternative</th>
|
||||
<th>Pros</th>
|
||||
<th>Cons</th>
|
||||
<th>Rejection Reason</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>MongoDB</td>
|
||||
<td>Schema flexibility, horizontal scaling</td>
|
||||
<td>Weak transaction support, complex queries difficult</td>
|
||||
<td>E-commerce requires strong ACID for financial data</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MySQL</td>
|
||||
<td>Widely adopted, good performance</td>
|
||||
<td>Limited JSON support, fewer features</td>
|
||||
<td>PostgreSQL offers better feature set</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Consequences</h4>
|
||||
<p><strong>Positive:</strong></p>
|
||||
<ul>
|
||||
<li>Data integrity guaranteed for financial transactions</li>
|
||||
<li>Rich ecosystem and tooling</li>
|
||||
</ul>
|
||||
<p><strong>Negative:</strong></p>
|
||||
<ul>
|
||||
<li>Vertical scaling limitations (mitigated by read replicas)</li>
|
||||
<li>Schema migrations require careful planning</li>
|
||||
</ul>
|
||||
</details>
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{SUCCESS_CRITERIA}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="success-criteria">
|
||||
<h3>Success Criteria</h3>
|
||||
<ul>
|
||||
<li>✅ MVP handles 1,000+ daily active users</li>
|
||||
<li>✅ 99.5% uptime in first 3 months</li>
|
||||
<li>✅ Average checkout time < 3 minutes</li>
|
||||
<li>✅ 85%+ test coverage (E2E + Integration + Unit)</li>
|
||||
<li>✅ Zero critical security vulnerabilities</li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
@@ -0,0 +1,315 @@
|
||||
<!-- SCOPE: Work Order & Scope Boundaries (NO Dates/Budgets) -->
|
||||
<!-- INCLUDES: Epic list with scope (in/out), dependencies, success criteria, status -->
|
||||
<!-- EXCLUDES: Specific dates/deadlines, Budget/costs, Team assignments, Individual tasks/stories, Implementation details → Technical Spec -->
|
||||
|
||||
<h2>Roadmap</h2>
|
||||
|
||||
<p class="roadmap-intro">This roadmap shows the <strong>work order</strong> and <strong>scope boundaries</strong> for our project. Epics are organized by dependencies, with clear scope definition for each.</p>
|
||||
|
||||
<!-- PLACEHOLDER: {{EPIC_CARDS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="epics-list">
|
||||
<!-- Epic 1: Done -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 1: User Management</h3>
|
||||
<span class="epic-status status-done">Done</span>
|
||||
</div>
|
||||
<p class="epic-description">User registration, authentication, profile management, and session handling</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>JWT authentication</li>
|
||||
<li>Email/password registration</li>
|
||||
<li>Password reset flow</li>
|
||||
<li>User profile CRUD operations</li>
|
||||
<li>Session management</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Social login (OAuth)</li>
|
||||
<li>Multi-factor authentication</li>
|
||||
<li>Single sign-on (SSO)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> None (Foundation epic)</p>
|
||||
<p><strong>Success Criteria:</strong> JWT authentication, < 2s login time, Password reset flow</p>
|
||||
<p><strong>Progress:</strong> 6/6 stories completed (100%)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 2: Done -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 2: Product Catalog</h3>
|
||||
<span class="epic-status status-done">Done</span>
|
||||
</div>
|
||||
<p class="epic-description">Product listing, search, filters, and pagination</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Full-text search across product names and descriptions</li>
|
||||
<li>Category filters</li>
|
||||
<li>Price range filters</li>
|
||||
<li>Pagination (20 items/page)</li>
|
||||
<li>Product detail pages</li>
|
||||
<li>1000+ SKUs support</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>AI-powered recommendations</li>
|
||||
<li>Visual search</li>
|
||||
<li>Product reviews</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 1 (User Management for admin features)</p>
|
||||
<p><strong>Success Criteria:</strong> Full-text search, 1000+ SKUs, < 1s search response</p>
|
||||
<p><strong>Progress:</strong> 8/8 stories completed (100%)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 3: In Progress -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 3: Shopping Cart</h3>
|
||||
<span class="epic-status status-progress">In Progress</span>
|
||||
</div>
|
||||
<p class="epic-description">Cart management with session persistence and inventory validation</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Add/remove items from cart</li>
|
||||
<li>Update quantities</li>
|
||||
<li>Cart persistence across sessions</li>
|
||||
<li>Real-time inventory validation</li>
|
||||
<li>Cart subtotal calculation</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Wishlist functionality</li>
|
||||
<li>Share cart</li>
|
||||
<li>Save for later</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 2 (Product Catalog)</p>
|
||||
<p><strong>Success Criteria:</strong> Cart persists across sessions, real-time inventory sync, < 500ms cart operations</p>
|
||||
<p><strong>Progress:</strong> 3/8 stories completed (37%)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 4: In Progress -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 4: Admin Dashboard</h3>
|
||||
<span class="epic-status status-progress">In Progress</span>
|
||||
</div>
|
||||
<p class="epic-description">Product management, inventory control, and analytics dashboard</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Product CRUD operations</li>
|
||||
<li>Bulk product import (CSV)</li>
|
||||
<li>Inventory management</li>
|
||||
<li>Role-based access control</li>
|
||||
<li>Real-time analytics dashboard</li>
|
||||
<li>Sales reports</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Customer support tickets</li>
|
||||
<li>Email campaigns</li>
|
||||
<li>Advanced BI reports</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 1 (User Management), Epic 2 (Product Catalog)</p>
|
||||
<p><strong>Success Criteria:</strong> Role-based access control, bulk product import, real-time analytics</p>
|
||||
<p><strong>Progress:</strong> 2/7 stories completed (28%)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 5: Todo -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 5: Payment Gateway</h3>
|
||||
<span class="epic-status status-todo">Todo</span>
|
||||
</div>
|
||||
<p class="epic-description">Integrate Stripe for secure payment processing with PCI DSS compliance</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Stripe payment integration</li>
|
||||
<li>Credit/debit card payments</li>
|
||||
<li>Digital wallets (Apple Pay, Google Pay)</li>
|
||||
<li>PCI DSS compliance</li>
|
||||
<li>Payment error handling</li>
|
||||
<li>Refund processing</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Cryptocurrency payments</li>
|
||||
<li>Buy now, pay later (BNPL)</li>
|
||||
<li>Invoice payments</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 3 (Shopping Cart)</p>
|
||||
<p><strong>Success Criteria:</strong> PCI DSS compliant, < 3s checkout time, support 5+ payment methods</p>
|
||||
<p><strong>Progress:</strong> 0/5 stories planned</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 6: Todo -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 6: Order Management</h3>
|
||||
<span class="epic-status status-todo">Todo</span>
|
||||
</div>
|
||||
<p class="epic-description">Order processing, tracking, and fulfillment workflows</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Order creation and confirmation</li>
|
||||
<li>Real-time order tracking</li>
|
||||
<li>Email notifications</li>
|
||||
<li>Order history</li>
|
||||
<li>Automated fulfillment workflows</li>
|
||||
<li>Cancellation and refund flows</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Advanced shipping integrations</li>
|
||||
<li>Returns management portal</li>
|
||||
<li>International shipping</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 5 (Payment Gateway)</p>
|
||||
<p><strong>Success Criteria:</strong> Real-time order tracking, automated fulfillment notifications, < 1min order confirmation</p>
|
||||
<p><strong>Progress:</strong> 0/6 stories planned</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Epic 7: Backlog -->
|
||||
<div class="epic-item">
|
||||
<div class="epic-header">
|
||||
<h3>Epic 7: Advanced Analytics</h3>
|
||||
<span class="epic-status status-backlog">Backlog</span>
|
||||
</div>
|
||||
<p class="epic-description">Customer behavior analytics and recommendations engine</p>
|
||||
|
||||
<div class="epic-details">
|
||||
<div class="epic-scope">
|
||||
<h4>In Scope</h4>
|
||||
<ul>
|
||||
<li>Customer behavior tracking</li>
|
||||
<li>Product recommendations engine</li>
|
||||
<li>Conversion funnel analytics</li>
|
||||
<li>A/B testing framework</li>
|
||||
<li>Personalized user experience</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="epic-scope">
|
||||
<h4>Out of Scope</h4>
|
||||
<ul>
|
||||
<li>Machine learning models</li>
|
||||
<li>Predictive analytics</li>
|
||||
<li>Customer data platform (CDP)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="epic-meta">
|
||||
<p><strong>Dependencies:</strong> Epic 2 (Product Catalog), Epic 6 (Order Management)</p>
|
||||
<p><strong>Success Criteria:</strong> 15% increase in conversion rate, personalized recommendations for 80%+ users</p>
|
||||
<p><strong>Progress:</strong> 0/9 stories planned</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{OUT_OF_SCOPE_ITEMS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="out-of-scope-items">
|
||||
<h3>Out of Project Scope</h3>
|
||||
<p>The following items are explicitly <strong>NOT included</strong> in the current project phase:</p>
|
||||
|
||||
<div class="out-of-scope-grid">
|
||||
<div class="out-of-scope-card">
|
||||
<h4>Mobile Native Apps</h4>
|
||||
<p>iOS and Android native applications</p>
|
||||
<p class="scope-reason"><strong>Reason:</strong> Focus on responsive web first, native apps planned for Phase 2</p>
|
||||
</div>
|
||||
|
||||
<div class="out-of-scope-card">
|
||||
<h4>Multi-Currency Support</h4>
|
||||
<p>International payments and currency conversion</p>
|
||||
<p class="scope-reason"><strong>Reason:</strong> Current scope limited to USD, internationalization in future release</p>
|
||||
</div>
|
||||
|
||||
<div class="out-of-scope-card">
|
||||
<h4>Social Commerce Integration</h4>
|
||||
<p>Social media selling and live shopping features</p>
|
||||
<p class="scope-reason"><strong>Reason:</strong> Not in MVP scope, evaluate after core features stable</p>
|
||||
</div>
|
||||
|
||||
<div class="out-of-scope-card">
|
||||
<h4>B2B Wholesale Portal</h4>
|
||||
<p>Bulk ordering and wholesale pricing for business customers</p>
|
||||
<p class="scope-reason"><strong>Reason:</strong> B2C focus first, B2B features separate project phase</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{ROADMAP_LEGEND}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="roadmap-legend">
|
||||
<h3>Status Legend</h3>
|
||||
<div class="status-badges">
|
||||
<span class="epic-status status-done">Done</span> Completed and deployed
|
||||
<span class="epic-status status-progress">In Progress</span> Currently being developed
|
||||
<span class="epic-status status-todo">Todo</span> Approved and ready to start
|
||||
<span class="epic-status status-backlog">Backlog</span> Under evaluation
|
||||
</div>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
@@ -0,0 +1,364 @@
|
||||
<!-- SCOPE: API Documentation & Technical Reference -->
|
||||
<!-- INCLUDES: API endpoints (methods, parameters, responses), Data models (schemas, ER diagrams), Infrastructure configuration, Deployment setup, Integration specifications -->
|
||||
<!-- EXCLUDES: Technology decisions → ADRs in Requirements, Business requirements → Requirements tab, System diagrams → Architecture, Work order → Roadmap, How-to tutorials → Guides -->
|
||||
|
||||
<h2>Technical Specification</h2>
|
||||
|
||||
<!-- PLACEHOLDER: {{TECH_STACK_TABLE}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="tech-stack">
|
||||
<h3>Technology Stack</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Category</th>
|
||||
<th>Technology</th>
|
||||
<th>Version</th>
|
||||
<th>Purpose</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Frontend</td>
|
||||
<td>React</td>
|
||||
<td>18.2</td>
|
||||
<td>UI framework for SPA</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Frontend</td>
|
||||
<td>TypeScript</td>
|
||||
<td>5.2</td>
|
||||
<td>Type-safe JavaScript</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Backend</td>
|
||||
<td>Node.js</td>
|
||||
<td>20.x</td>
|
||||
<td>Runtime environment</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Backend</td>
|
||||
<td>Express</td>
|
||||
<td>4.18</td>
|
||||
<td>REST API framework</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Database</td>
|
||||
<td>PostgreSQL</td>
|
||||
<td>15.x</td>
|
||||
<td>Primary transactional database</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cache</td>
|
||||
<td>Redis</td>
|
||||
<td>7.x</td>
|
||||
<td>Session & cart caching</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Infrastructure</td>
|
||||
<td>Docker</td>
|
||||
<td>24.x</td>
|
||||
<td>Containerization</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Infrastructure</td>
|
||||
<td>AWS ECS</td>
|
||||
<td>-</td>
|
||||
<td>Container orchestration</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DevOps</td>
|
||||
<td>GitHub Actions</td>
|
||||
<td>-</td>
|
||||
<td>CI/CD pipeline</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{API_ENDPOINTS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="api-reference">
|
||||
<h3>API Endpoints</h3>
|
||||
|
||||
<h4>Authentication</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Endpoint</th>
|
||||
<th>Method</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>/api/auth/register</code></td>
|
||||
<td>POST</td>
|
||||
<td>Register new user</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/auth/login</code></td>
|
||||
<td>POST</td>
|
||||
<td>Login and get JWT token</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/auth/refresh</code></td>
|
||||
<td>POST</td>
|
||||
<td>Refresh JWT token</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Products</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Endpoint</th>
|
||||
<th>Method</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>/api/products</code></td>
|
||||
<td>GET</td>
|
||||
<td>List all products (paginated)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/products/:id</code></td>
|
||||
<td>GET</td>
|
||||
<td>Get product details</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/products</code></td>
|
||||
<td>POST</td>
|
||||
<td>Create new product (admin only)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/products/:id</code></td>
|
||||
<td>PUT</td>
|
||||
<td>Update product (admin only)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Shopping Cart</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Endpoint</th>
|
||||
<th>Method</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>/api/cart</code></td>
|
||||
<td>GET</td>
|
||||
<td>Get current user's cart</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/cart/items</code></td>
|
||||
<td>POST</td>
|
||||
<td>Add item to cart</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/cart/items/:id</code></td>
|
||||
<td>PUT</td>
|
||||
<td>Update item quantity</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>/api/cart/items/:id</code></td>
|
||||
<td>DELETE</td>
|
||||
<td>Remove item from cart</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Authentication</h4>
|
||||
<p><strong>Method:</strong> JWT Bearer Token</p>
|
||||
<pre><code>Authorization: Bearer <token></code></pre>
|
||||
<p>Token expires in 15 minutes. Use <code>/api/auth/refresh</code> with refresh token to get new access token.</p>
|
||||
|
||||
<h4>Error Codes</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Code</th>
|
||||
<th>Message</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>400</td>
|
||||
<td>Bad Request</td>
|
||||
<td>Invalid request payload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>401</td>
|
||||
<td>Unauthorized</td>
|
||||
<td>Missing or invalid JWT token</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>403</td>
|
||||
<td>Forbidden</td>
|
||||
<td>Insufficient permissions</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>404</td>
|
||||
<td>Not Found</td>
|
||||
<td>Resource not found</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>500</td>
|
||||
<td>Internal Server Error</td>
|
||||
<td>Unexpected server error</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{DATA_MODELS}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="data-models">
|
||||
<h3>Data Models</h3>
|
||||
|
||||
<h4>Entity Relationship Diagram</h4>
|
||||
<div class="mermaid">
|
||||
erDiagram
|
||||
USER ||--o{ ORDER : places
|
||||
USER ||--o{ CART : has
|
||||
CART ||--|{ CART_ITEM : contains
|
||||
PRODUCT ||--o{ CART_ITEM : "in"
|
||||
PRODUCT ||--o{ ORDER_ITEM : "in"
|
||||
ORDER ||--|{ ORDER_ITEM : contains
|
||||
ORDER ||--|| PAYMENT : has
|
||||
|
||||
USER {
|
||||
uuid id PK
|
||||
string email
|
||||
string password_hash
|
||||
string first_name
|
||||
string last_name
|
||||
timestamp created_at
|
||||
}
|
||||
|
||||
PRODUCT {
|
||||
uuid id PK
|
||||
string name
|
||||
text description
|
||||
decimal price
|
||||
int stock_quantity
|
||||
string category
|
||||
timestamp created_at
|
||||
}
|
||||
|
||||
CART {
|
||||
uuid id PK
|
||||
uuid user_id FK
|
||||
timestamp updated_at
|
||||
}
|
||||
|
||||
CART_ITEM {
|
||||
uuid id PK
|
||||
uuid cart_id FK
|
||||
uuid product_id FK
|
||||
int quantity
|
||||
}
|
||||
|
||||
ORDER {
|
||||
uuid id PK
|
||||
uuid user_id FK
|
||||
decimal total_amount
|
||||
string status
|
||||
timestamp created_at
|
||||
}
|
||||
|
||||
ORDER_ITEM {
|
||||
uuid id PK
|
||||
uuid order_id FK
|
||||
uuid product_id FK
|
||||
int quantity
|
||||
decimal price_at_purchase
|
||||
}
|
||||
|
||||
PAYMENT {
|
||||
uuid id PK
|
||||
uuid order_id FK
|
||||
string payment_method
|
||||
string status
|
||||
string transaction_id
|
||||
timestamp created_at
|
||||
}
|
||||
</div>
|
||||
|
||||
<h4>Data Dictionary</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Entity</th>
|
||||
<th>Key Attributes</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>USER</td>
|
||||
<td>email (unique), password_hash</td>
|
||||
<td>Customer accounts</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PRODUCT</td>
|
||||
<td>name, price, stock_quantity</td>
|
||||
<td>Product catalog items</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>CART</td>
|
||||
<td>user_id</td>
|
||||
<td>Shopping cart (1 per user)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ORDER</td>
|
||||
<td>user_id, status, total_amount</td>
|
||||
<td>Customer orders</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PAYMENT</td>
|
||||
<td>order_id, transaction_id, status</td>
|
||||
<td>Payment transactions</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
|
||||
<!-- PLACEHOLDER: {{TESTING_STRATEGY}} -->
|
||||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||||
<section class="testing-strategy">
|
||||
<h3>Testing Strategy</h3>
|
||||
<p><strong>Risk-Based Testing approach</strong> - prioritize tests by business impact:</p>
|
||||
|
||||
<h4>Test Pyramid</h4>
|
||||
<ul>
|
||||
<li><strong>E2E Tests (2-5 per Story):</strong> Critical user flows (checkout, payment, registration)</li>
|
||||
<li><strong>Integration Tests (3-8 per Story):</strong> API endpoints, database interactions</li>
|
||||
<li><strong>Unit Tests (5-15 per Story):</strong> Business logic, validators, utilities</li>
|
||||
</ul>
|
||||
|
||||
<p><strong>Total:</strong> 10-28 tests per Story (max)</p>
|
||||
|
||||
<h4>Priority Matrix</h4>
|
||||
<p>Test scenarios with <strong>Priority ≥ 15</strong> MUST be tested:</p>
|
||||
<pre><code>Priority = Business Impact (1-5) × Probability (1-5)</code></pre>
|
||||
|
||||
<h4>Test Focus</h4>
|
||||
<ul>
|
||||
<li>✅ Test OUR code (business logic, API endpoints)</li>
|
||||
<li>❌ Skip framework code (Express middleware already tested)</li>
|
||||
<li>❌ Skip trivial getters/setters (no business logic)</li>
|
||||
</ul>
|
||||
</section>
|
||||
<!-- EXAMPLE END -->
|
||||
Reference in New Issue
Block a user