Template Version: v5.0.0 (Session 44 - Governance Template Consolidation)
Part of EVA Foundry Workspace | Data Model | Veritas Audit
Workspace Skills: @sprint-advance | @progress-report | @gap-report | @sprint-report | @veritas-expert
| Resource | Link |
|---|---|
| Project Record | GET https://msub-eva-data-model.victoriousgrass-30debbd3.canadacentral.azurecontainerapps.io/model/projects/03-poc-enhanced-docs |
| Live Session Data | GET .../model/project_work/?project_id=03-poc-enhanced-docs&$orderby=id%20desc&$limit=10 |
| Veritas Audit | Run audit_repo MCP tool on C:\eva-foundry\03-poc-enhanced-docs |
| Trust Score | Run get_trust_score MCP tool on C:\eva-foundry\03-poc-enhanced-docs |
| Sync to Model | Run sync_repo MCP tool (full paperless DPDCA audit + write-back) |
| Governance | PLAN.md | STATUS.md | ACCEPTANCE.md |
| Instructions | .github/copilot-instructions.md |
This POC transforms the 28 generated EVA Foundation markdown files into a professional, interactive HTML documentation site with:
- 40+ Mermaid diagrams (architecture, workflows, data flows)
- Enhanced markdown (callouts, cross-references, tabs)
- MkDocs Material theme with ESDC branding
- Interactive features (search, navigation, tooltips)
Convert AI-generated markdown into stakeholder-ready documentation that:
- Visual First: Every architecture/process concept has a diagram
- Interactive: Stakeholders can navigate, search, and explore
- Professional: ESDC branding, consistent styling, high-quality rendering
- Maintainable: MkDocs configuration can be regenerated as content evolves
- Generate Diagrams: Create 40+ Mermaid diagrams covering all architecture and process flows
- Enhance Markdown: Add callouts, cross-references, tabs, and enhanced formatting
- Build HTML Site: Configure MkDocs with Material theme and ESDC branding
- Deploy: Host on Azure Static Web Apps or GitHub Pages
diagram-generator/
??? generator.py # Main diagram generation tool
??? templates/ # Mermaid diagram templates
? ??? architecture.yaml # Architecture diagram patterns
? ??? sequence.yaml # Sequence diagram patterns
? ??? data-flow.yaml # Data flow diagram patterns
? ??? deployment.yaml # Deployment diagram patterns
??? output/ # Generated diagrams (40+ .mmd files)
diagram-templates/
??? system-architecture.mmd # High-level system view
??? data-pipeline.mmd # Document processing flow
??? security-layers.mmd # Security architecture
??? deployment-topology.mmd # Azure resource deployment
??? ... (35+ more)
mkdocs-config/
??? mkdocs.yml # MkDocs configuration
??? theme-overrides/ # ESDC custom styling
? ??? esdc-colors.css
? ??? esdc-logo.png
??? plugins-config.yaml # Plugin settings (search, diagrams, etc.)
??? docs/ # Enhanced markdown (copied from output/)
AI-powered tool that analyzes markdown content and generates appropriate diagrams:
# Example usage
generator = DiagramGenerator(
input_dir="docs/eva-foundation/generated-output/markdown/",
output_dir="docs/eva-foundation/projects/03-poc-enhanced-docs/diagram-output/"
)
# Generate diagrams for all files
diagrams = generator.generate_all_diagrams(
diagram_types=["architecture", "sequence", "data-flow", "deployment"]
)
# Output: 40+ .mmd files with Mermaid diagram codeDiagram Types:
- Architecture Diagrams (15 diagrams): System components, layers, integrations
- Sequence Diagrams (10 diagrams): User workflows, API interactions, authentication flows
- Data Flow Diagrams (8 diagrams): Document pipeline, indexing, search process
- Deployment Diagrams (7 diagrams): Azure resources, network topology, security zones
Augments generated markdown with interactive features:
enhancer = MarkdownEnhancer()
# Add callouts
enhancer.add_callouts(
file="platform-overview.md",
callout_type="info",
text="This section describes the core architecture..."
)
# Add cross-references
enhancer.add_cross_references(
source="platform-overview.md",
target="security-architecture.md",
link_text="See Security Architecture"
)
# Add tabbed content
enhancer.add_tabs(
file="platform-overview.md",
tabs=["Azure Services", "Open Source Components", "Custom Code"]
)Enhancement Features:
- Callouts: Info, warning, tip, danger boxes
- Cross-References: Automatic linking between related sections
- Tabs: Organize alternative content (e.g., Azure vs on-prem)
- Collapsible Sections: Hide detailed content behind expandable headers
- Image Galleries: Diagram galleries with lightbox
Professional MkDocs Material theme with ESDC branding:
# mkdocs.yml
site_name: EVA Foundation - Protected B Information Assistant
site_description: Enterprise-grade secure document Q&A system
site_author: ESDC - HC CLD2 Team
theme:
name: material
palette:
primary: blue-grey # ESDC brand colors
accent: indigo
logo: assets/esdc-logo.png
favicon: assets/favicon.ico
features:
- navigation.tabs
- navigation.sections
- navigation.top
- search.suggest
- search.highlight
- content.code.annotate
- content.tabs.link
plugins:
- search
- mermaid2 # Render Mermaid diagrams
- minify # Optimize HTML/CSS/JS
- git-revision-date-localized # Show last updated dates
markdown_extensions:
- admonition # Callouts
- pymdownx.details # Collapsible sections
- pymdownx.superfences # Code fences
- pymdownx.tabbed # Tabs
- pymdownx.tasklist # Task lists
- toc:
permalink: true- executive-summary.md:
- System overview diagram (high-level architecture)
- Stakeholder engagement model
- platform-overview.md:
- Platform component architecture
- Technology stack layers
- glossary-acronyms.md:
- (No diagrams needed - table format)
- system-architecture.md:
- System architecture diagram (layers: Frontend, Backend, AI Services, Data)
- Component interaction sequence
- security-architecture.md:
- Security layers diagram (network, identity, data, application)
- Authentication flow (Entra ID OAuth)
- integration-architecture.md:
- Integration points diagram (Azure services, external systems)
- API architecture
- data-architecture.md:
- Data flow diagram (document ingestion ? search)
- Storage architecture (Blob, Cosmos, Search)
- frontend-components.md:
- React component hierarchy
- User interaction flow
- backend-components.md:
- Backend service architecture
- API endpoint mapping
- ai-orchestration.md:
- RAG pipeline sequence diagram
- LLM orchestration flow
- document-processing.md:
- Document processing pipeline (Azure Functions)
- OCR ? Chunking ? Embedding flow
- search-retrieval.md:
- Hybrid search architecture (vector + keyword)
- Query optimization flow
- llm-integration.md:
- LLM integration sequence
- Prompt engineering workflow
- data-persistence.md:
- Data persistence architecture (Cosmos DB, Blob Storage)
- Session management flow
- identity-access-management.md:
- IAM architecture (Entra ID)
- RBAC model
- network-security.md:
- Network topology (VNet, private endpoints)
- Security zones
- data-protection.md:
- Encryption layers (at-rest, in-transit)
- Key management architecture
- audit-compliance.md:
- Audit logging flow
- Compliance reporting architecture
- deployment-guide.md:
- Deployment topology (Azure resources)
- CI/CD pipeline
- monitoring-alerting.md:
- Monitoring architecture (Azure Monitor, App Insights)
- Alerting flow
- incident-response.md:
- Incident response workflow
- maintenance-operations.md:
- Maintenance workflow (updates, backups)
- user-training.md:
- Training flow (user onboarding)
- testing-strategy.md:
- Testing pyramid (unit, integration, functional)
- performance-optimization.md:
- Performance optimization workflow
- quality-assurance.md:
- (No additional diagrams)
- requirements-traceability-matrix.md:
- Requirements traceability visualization
- technical-decisions.md:
- (No additional diagrams)
Total: 40 diagrams across 28 files
- Build diagram generator tool (Day 1-2)
- Create 15 Mermaid diagram templates (Day 2-3)
- Generate all 40+ diagrams (Day 3-4)
- Manual review and refinement (Day 5)
- Build markdown enhancer tool (Day 6)
- Enhance all 28 markdown files (Day 7-8)
- Configure MkDocs with Material theme (Day 9)
- Apply ESDC branding (Day 10)
- Add interactive features (tooltips, zoom) (Day 11-12)
- Testing (Day 13): Cross-browser, accessibility, performance
- Deploy to Azure Static Web Apps (Day 14)
- Documentation and demo (Day 15)
- ? 40+ Diagrams Generated: All architecture and process flows visualized
- ? Professional HTML Site: MkDocs Material theme with ESDC branding
- ? Interactive Navigation: Search, tabs, collapsible sections work
- ? Accessibility: WCAG 2.1 AA compliant (keyboard nav, screen reader support)
- ? Performance: <3s page load time, mobile-responsive
- ? Deployment: Live site accessible to stakeholders
POC #2 capabilities can be packaged as agent skills:
- DiagramGeneratorSkill: Analyzes markdown, generates Mermaid diagrams
- MarkdownEnhancerSkill: Adds callouts, cross-refs, tabs
- MkDocsBuilderSkill: Configures and builds HTML site
Workflow:
DocumentationGeneratorSkill (POC #1)
? DiagramGeneratorSkill (POC #2)
? MarkdownEnhancerSkill (POC #2)
? MkDocsBuilderSkill (POC #2)
- Diagram Editing: Web-based diagram editor for stakeholders
- Version Control: Track diagram changes across documentation versions
- Multi-Language: Translate diagrams and docs to French
- PDF Export: Generate PDF documentation with embedded diagrams
- Live Reload: MkDocs live preview during editing
See PLAN.md for detailed 3-week implementation plan.
This POC is located at: docs/eva-foundation/projects/03-poc-enhanced-docs/
Source markdown: docs/eva-foundation/generated-output/markdown/