# surviveplus/evm-report architecture

> Architecture diagram of the GitHub repository surviveplus/evm-report, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/surviveplus/evm-report
- Repository: https://github.com/surviveplus/evm-report

## Overview

##### Project type and purpose
- This is an open‐source asset/tool rather than a monolithic application.
- Purpose: Provide Excel templates and a Power BI template (.pbit) so that traditional Earned Value Management (EVM) metrics (CPI, SPI, PV, EV, BAC) can be reported using data from VSTS/TFS.

##### File structure
- Root:
- README.md and LICENSE – general project metadata
- .gitignore – version control settings
- Asset/
- DataSource TFS-EVM.xltx – Excel template to extract and store TFS history
- Export For EVM.wiq – (optional) query definitions
- Report TFS-EVM.pbit – Power BI report template
- Other .xltx variants – alternate management modes
- HowToUse/
- HowToUse.md – step‐by‐step instructions
- images/ – visual walkthroughs

##### README for additional insights
- Data flow is manual today:
1. Run queries against TFS/VSTS
2. Populate the Excel history template
3. Load that Excel into Power BI Desktop using the .pbit
4. Generate interactive EVM dashboards
- Future vision: replace manual Excel step with a VSTS extension for automation.

##### Main components
a. External System
- VSTS/TFS REST API or direct database – the source of work‐item and historical data
b. Manual Extraction/Transformation
- Excel templates (Asset/DataSource TFS-EVM.xltx and related .wiq)
c. Data Store
- The generated Excel workbook holding historical snapshots
d. Reporting Engine
- Power BI Desktop using Report TFS-EVM.pbit
e. End User
- Project manager or analyst who reviews dashboards
f. (Future) Automation Layer
- Planned VSTS extension to automate data pull

##### Architectural patterns and design principles
- ETL pipeline (Extract → Transform → Load)
- Clear separation of concerns:
- Data extraction & storage (Excel)
- Presentation layer (Power BI)
- Documentation and instructions (HowToUse)
- Extensibility point: the VSTS extension sits between Extraction and Storage.

##### Relevant technologies and frameworks
- Microsoft Excel (templates in .xltx)
- Power BI Desktop (.pbit files)
- VSTS/TFS (REST API or WIQ queries)
- Markdown for docs

##### Diagramming conventions
- Rounded rectangles for external systems (TFS/VSTS REST API)
- Rectangles for processing steps (Excel template, Power BI engine)
- Blue for external systems
- Green for data stores
- Orange for processing steps

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External System
    VSTS_TFS["VSTS/TFS REST API"]:::external

    subgraph "Manual Extraction/Transformation"
        ExcelTemplate["DataSource TFS-EVM.xltx"]:::process
        WIQ["Export For EVM.wiq"]:::process
        Alt1["TFS-EVM (Bugs are managed with requirement).xltx"]:::process
        Alt2["TFS-EVM (Bugs are managed with task).xltx"]:::process
    end

    Workbook["Excel Workbook (Snapshot)"]:::datastore

    PowerBI["Report TFS-EVM.pbit"]:::process

    EndUser["Project Manager / Analyst"]:::external

    subgraph "Documentation & Metadata"
        README["README.md"]:::docs
        License["LICENSE"]:::docs
        HowToUseGuide["HowToUse.md"]:::docs
        Images["images/"]:::docs
    end

    VSTS_TFS -->|"Extract"| ExcelTemplate
    VSTS_TFS -->|"Extract"| WIQ
    VSTS_TFS -->|"Extract"| Alt1
    VSTS_TFS -->|"Extract"| Alt2

    ExcelTemplate -->|"Transform"| Workbook
    WIQ -->|"Transform"| Workbook
    Alt1 -->|"Transform"| Workbook
    Alt2 -->|"Transform"| Workbook

    Workbook -->|"Load"| PowerBI
    PowerBI -->|"Render"| EndUser

    VSTSExt["VSTS Extension (planned)"]:::future
    VSTSExt -.->|"Automated ETL"| Workbook

    %% Click Events
    click ExcelTemplate "https://github.com/surviveplus/evm-report/blob/master/Asset/DataSource TFS-EVM.xltx"
    click WIQ "https://github.com/surviveplus/evm-report/blob/master/Asset/Export For EVM.wiq"
    click Alt1 "https://github.com/surviveplus/evm-report/blob/master/Asset/TFS-EVM (Bugs are managed with requirement).xltx"
    click Alt2 "https://github.com/surviveplus/evm-report/blob/master/Asset/TFS-EVM (Bugs are managed with task).xltx"
    click PowerBI "https://github.com/surviveplus/evm-report/blob/master/Asset/Report TFS-EVM.pbit"
    click HowToUseGuide "https://github.com/surviveplus/evm-report/blob/master/HowToUse/HowToUse.md"
    click Images "https://github.com/surviveplus/evm-report/tree/master/HowToUse/images/"
    click README "https://github.com/surviveplus/evm-report/blob/master/README.md"
    click License "https://github.com/surviveplus/evm-report/tree/master/LICENSE"

    classDef external fill:#cce5ff,stroke:#004085,color:#004085
    classDef process fill:#ffe5b4,stroke:#994d00,color:#994d00
    classDef datastore fill:#d4edda,stroke:#155724,color:#155724
    classDef future fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 2
    classDef docs fill:#f8f9fa,stroke:#6c757d,color:#343a40
```
