Documentation Technical Workflow

This diagram illustrates how the Daktela documentation system works from a technical perspective.

Documentation Creation Sources

flowchart TB
    subgraph TOP[" "]
        direction LR
        subgraph SOURCES["User Input"]
            CU[("**ClickUp**<br/>PRDs & Tickets")]
            GL[("**GitLab**<br/>Code & Commits")]
            FG[("**Figma**<br/>UI Designs")]
        end

        subgraph GENERATOR["Claude Code Aggregation"]
            GEN[Claude Code]
            AGG[Aggregate by<br/>ticket number]
            OUT[Generate markdown]
            GEN --> AGG --> OUT
        end
    end

    subgraph LOCAL["Human Review"]
        direction LR
        EDIT[Edit & review] --> PREVIEW[mkdocs serve] --> COMMIT[Commit] --> PUSH[Push to updates]
    end

    CU --> GEN
    GL --> GEN
    FG --> GEN
    OUT --> EDIT

    style CU fill:#7b68ee,color:#fff
    style GL fill:#fc6d26,color:#fff
    style FG fill:#a259ff,color:#fff
    style GEN fill:#1976d2,color:#fff
    style PUSH fill:#4caf50,color:#fff
    style TOP fill:none,stroke:none

Review & Deployment Pipeline

flowchart TB
    subgraph TOP[" "]
        direction LR
        subgraph LOCAL["👤 Local Development"]
            D[Push to updates branch]
        end

        subgraph REVIEW["🔍 Review Process"]
            E[Create Merge Request] --> F[Reviewer reviews]
            F --> G{Approved?}
            G -->|Yes| I[Merge into main]
            G -->|No| H[Request changes]
            H --> D
        end
    end

    subgraph BOTTOM[" "]
        direction LR
        subgraph CICD["⚙️ GitLab CI/CD"]
            J[Pipeline triggered] --> M[mkdocs build]
        end

        subgraph DEPLOY["🚀 Deployment"]
            O[rsync to server] --> Q[docs.daktela.com]
        end
    end

    D --> E
    I --> J
    M --> O

    style LOCAL fill:#e1f5fe
    style REVIEW fill:#fff3e0
    style CICD fill:#f3e5f5
    style DEPLOY fill:#e8f5e9
    style TOP fill:none,stroke:none
    style BOTTOM fill:none,stroke:none

Documentation Creation Workflows

1. ClickUp Workflow

PRDs and feature specifications are managed in ClickUp with ticket numbers.

Step	Action
1	Create ClickUp task with ticket number (e.g., Feature #123456)
2	Add requirements, specs, and context to task description
3	Ticket number links all related work across systems

Ticket number formats supported: - Task name: Feature #123456 - Custom field "Ticket Number": 123456 - ClickUp Custom ID: PROJ-123

2. GitLab Codebase Workflow

Code commits reference ticket numbers to link implementation details.

Step	Action
1	Developers implement feature in codebase
2	Commits include ticket reference: fix: update login flow #123456
3	Generator searches commits by ticket number

3. Figma Workflow

UI/UX designs provide visual documentation and screenshots.

Step	Action
1	Designers create mockups in Figma
2	Generator exports screenshots with --export-screenshots flag
3	Images are embedded in generated documentation

4. Documentation Generator

The generator aggregates all sources into draft documentation.

# Generate docs for ticket #123456
./generate_docs.py 123456 -p contact-centre -v 2025.2

# With Figma screenshots
./generate_docs.py 123456 -p contact-centre -t feature --export-screenshots

Required API tokens: - ClickUp: app.clickup.com/settings/apps - GitLab: gitlab.daktela.com/-/profile/personal_access_tokens - Figma: www.figma.com/settings (optional)

Component Details

Local Development

Component	Description
MkDocs	Static site generator for documentation
Material Theme	Modern, responsive documentation theme
mkdocs serve	Local preview server (http://localhost:8000)
Doc Generator	Aggregates ClickUp, GitLab, and Figma sources

CI/CD Pipeline

Stage	Action
Trigger	Push to main branch
Container	squidfunk/mkdocs-material:latest
Build	mkdocs build → output/ directory
Deploy	rsync -avzP --delete to production

Infrastructure

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   ClickUp    │  │    GitLab    │  │    Figma     │
│  (PRDs &     │  │  (Commits &  │  │  (UI/UX      │
│   Tickets)   │  │   Code)      │  │   Designs)   │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └────────────────┬┴─────────────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Doc Generator      │
              │  generate_docs.py   │
              └──────────┬──────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     GitLab Repository                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   updates   │───▶│    main     │───▶│  CI/CD      │     │
│  │   branch    │ MR │   branch    │    │  Pipeline   │     │
│  └─────────────┘    └─────────────┘    └──────┬──────┘     │
└──────────────────────────────────────────────│──────────────┘
                                               │
                                               ▼
                              ┌────────────────────────────────┐
                              │     Production Server          │
                              │  vmakestest.daktela.com        │
                              │  ┌──────────────────────────┐  │
                              │  │   /opt/doc/              │  │
                              │  │   ├── en/                │  │
                              │  │   ├── cs/                │  │
                              │  │   └── assets/            │  │
                              │  └──────────────────────────┘  │
                              └────────────────────────────────┘

Quick Reference

Local preview:

mkdocs serve
# or using Docker:
docker run --rm -v "$(pwd):/docs" -p 8000:8000 squidfunk/mkdocs-material:latest serve -a 0.0.0.0:8000

Manual build:

./scripts/build-docs.sh

Key files: - mkdocs.yml - Main MkDocs configuration - .gitlab-ci.yml - CI/CD pipeline definition - .doc-generator/ - Documentation generator tool - docs/ - Source documentation (Markdown) - output/ - Built site (generated)

End-to-End Example

1. PM creates ClickUp task: "Add dark mode toggle #789012"
2. Developer commits: "feat: implement dark mode #789012"
3. Designer uploads Figma mockups for dark mode UI
                            ↓
4. Run: ./generate_docs.py 789012 -p contact-centre --export-screenshots
                            ↓
5. Generator outputs draft markdown with:
   - Feature description from ClickUp PRD
   - Technical details from GitLab commits
   - Screenshots from Figma designs
                            ↓
6. Author reviews, edits, runs mkdocs serve
7. Push to updates branch → Merge Request
8. Reviewer approves → Merge to main
9. CI/CD builds & deploys to production