UTMB Canvas Power Apps Projects

A multi-project repository for managing Microsoft Canvas Power Apps using version control and a template-based workflow inspired by SQL Server's model database pattern.

Overview

This repository provides a structured approach to managing multiple Canvas Power Apps projects with:

• Version control for Power Apps source code
• Template-based workflow for consistent project structure
• PAC CLI integration for downloading, unpacking, and managing apps
• Documentation standards for each project
• TaskMaster protocol for task tracking and session management
• Dual git remotes for redundant backups

Repository Structure

utmb-projects/
├── .taskmaster/                 # TaskMaster task tracking
│   ├── tasks.json              # Task database
│   └── config.json             # TaskMaster configuration
├── CLAUDE.md                    # AI assistant guidance
├── README.md                    # This file
├── handoff.md                   # Session handoff documentation
└── projects/
    ├── .model/                  # Template folder (do not modify)
    │   ├── README.md
    │   ├── msapp-down/          # Downloaded .msapp files
    │   ├── msapp-extracted/     # Unpacked source
    │   └── docs/                # Documentation
    │
    └── [project-name]/          # Individual projects
        ├── README.md            # Project-specific docs
        ├── msapp-down/
        ├── msapp-extracted/
        └── docs/

🛠️ Tools & Protocols

This repository uses several tools and protocols to maintain code quality and project organization:

TaskMaster Protocol

Purpose: Systematic task tracking and session management

• Location: .taskmaster/ directory
• Core Files:
  • tasks.json - Task database with status, priority, and metadata
  • config.json - Project configuration and integration settings
• Session Protocol:
  1. Start: Read .taskmaster/tasks.json and handoff.md first
  2. During: Update task status (pending → in-progress → completed)
  3. Complete: Mark tasks as done immediately, update handoff.md
• Integration: Auto-synced with handoff.md for session continuity

Quick Commands:

# View all tasks
cat .taskmaster/tasks.json | jq '.tasks[] | {id, title, status, priority}'

# View task summary
cat .taskmaster/tasks.json | jq '.metadata'

Handoff Documentation

Purpose: Session state tracking and context preservation (saves 90% of tokens between sessions)

• Location: handoff.md (root directory)
• Contents:
  • Completed work this session
  • In-progress tasks with status
  • Pending tasks and priorities
  • Key file locations and gotchas
  • Next session priorities
• Update Frequency: After significant work or before session end
• Sync Rule: Completion % must match TaskMaster tasks.json

Dual Git Remotes

Purpose: Redundant backups and version control

• origin: git.superpowerlabs.app (Primary Gitea server)
• alt: ssh://git@pool:2222/darren/utmb-projects (NAS backup)
• Setup: Use /zremotes skill to configure both remotes
• Workflow: Always push to both remotes

# Push to both remotes
git push origin main && git push alt main

# Or use aliases
git push origin main
git push alt main

Power Platform CLI (PAC CLI)

Purpose: Download, unpack, and manage Canvas Apps for version control

• Version Required: 1.51.1+
• Install: https://aka.ms/PowerPlatformCLI
• Authentication: pac auth create --url https://[your-org].crm.dynamics.com
• Common Commands: See PAC CLI Reference section below

Quick Start

Prerequisites

1. Install PAC CLI (Power Platform CLI)

   • Download: https://aka.ms/PowerPlatformCLI
   • Verify: pac (should show version 1.51.1+)

2. Authenticate to Power Platform

   pac auth create --url https://[your-org].crm.dynamics.com
   

Creating a New Project

Option 1: Starting with an Existing App (Brownfield)

1. Copy the template folder:

   cp -r projects/.model projects/my-new-project
   cd projects/my-new-project
   

2. List available apps and find your app ID:

   pac canvas list
   

3. Download the app:

   pac canvas download --id [app-id] --name "2026-01-12"
   

4. Unpack for version control:

   pac canvas unpack --msapp "./msapp-down/2026-01-12.msapp" --sources "./msapp-extracted"
   

5. Update README.md with project details (App ID, environment, etc.)

6. Commit to Git:

   git add .
   git commit -m "feat: add my-new-project canvas app"
   

Option 2: Starting a New App (Greenfield)

1. Create the app in Power Apps Studio first
2. Follow Option 1 steps to bring it into this repository

Working with an Existing Project

1. Make changes in Power Apps Studio (https://make.powerapps.com)

2. Download the updated app:

   cd projects/[project-name]
   pac canvas download --id [app-id] --name "$(date +%Y-%m-%d)"
   

3. Unpack the updated version:

   pac canvas unpack --msapp "./msapp-down/YYYY-MM-DD.msapp" --sources "./msapp-extracted"
   

4. Review and commit changes:

   git diff msapp-extracted/
   git add msapp-extracted/
   git commit -m "feat: add user authentication screen"
   git push origin main
   git push pool main
   

The Template Pattern

The .model folder works like SQL Server's model database:

• Purpose: Provides consistent structure for all projects
• Usage: Copy .model folder and rename for each new project
• Do not modify: Keep .model as a clean template

Folder Structure Explained

Folder/File	Purpose
.taskmaster/	TaskMaster task tracking and configuration
handoff.md	Session state and handoff documentation
msapp-down/	Store downloaded .msapp files (binary ZIP archives)
msapp-extracted/	Unpacked source files for version control and diffs
docs/	Project-specific documentation, diagrams, notes
README.md	Project metadata and status

PAC CLI Reference

Common Commands

Command	Purpose
pac auth list	List authentication profiles
pac auth create --url [url]	Authenticate to environment
pac canvas list	List all canvas apps
pac canvas download --id [id] --name [name]	Download app as .msapp
pac canvas unpack --msapp [path] --sources [path]	Unpack .msapp to source files
pac canvas pack --sources [path] --msapp [path]	Pack source files to .msapp
pac canvas validate --sources [path]	Validate unpacked source files

Full Documentation

• PAC CLI: https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction?tabs=windows
• Canvas Apps: https://learn.microsoft.com/en-us/power-apps/maker/canvas-apps/

Project Status

Project	App ID	Status	Last Updated
projects-tasks	9d117b6f-5980-41f9-bf94-7e4d03de5175	Active	2026-01-12

Best Practices

Task Management

• Read TaskMaster first at start of each session (.taskmaster/tasks.json)
• Update task status in real-time as you work (pending → in-progress → completed)
• Mark tasks complete immediately when finished (don't batch completions)
• Keep handoff.md synced with task completion percentages
• Review handoff.md for context before starting work (saves token usage)

Version Control

• Always unpack .msapp files to msapp-extracted/ for readable diffs
• Commit both the .msapp (binary) and extracted source
• Use descriptive commit messages with project name
• Branch naming: feature/[project]-[feature], fix/[project]-[issue]

Asset Management

• Optimize images before adding to apps (compress PNGs, use SVGs)
• Track asset sizes - large images bloat the repository
• Review asset changes in commits to catch unintended additions

Documentation

• Update README.md for each project with:
  • App ID and environment URL
  • Data sources (SharePoint lists, Dataverse tables)
  • Key screens and functionality
  • Last download date
  • Current status

Git Remotes

This repository pushes to two remotes:

• origin: git.superpowerlabs.app
• pool: ssh://git@pool:2222/darren/utmb-projects (NAS backup)

Push to both:

git push origin main && git push pool main

Troubleshooting

PAC CLI Authentication Issues

# List auth profiles
pac auth list

# Clear and re-authenticate
pac auth clear
pac auth create --url https://[your-org].crm.dynamics.com

Unpack Fails

• Ensure .msapp file is not corrupted
• Check PAC CLI version: pac
• Try re-downloading the app

Large Repository Size

• Large .msapp files are binary and will grow the repo
• Consider using Git LFS for .msapp files if size becomes an issue
• Optimize images in apps before downloading

Contributing

When working on projects in this repository:

1. Check TaskMaster - Read .taskmaster/tasks.json and handoff.md first
2. Create task - Add new task to TaskMaster if starting new work
3. Create feature branch from main (if needed)
4. Make changes in Power Apps Studio
5. Download and unpack the updated app
6. Review changes with git diff
7. Commit with descriptive messages
8. Update TaskMaster - Mark tasks as completed, update handoff.md
9. Push to both remotes - origin and alt

Support

• PAC CLI Issues: https://github.com/microsoft/powerplatform-build-tools/discussions
• Power Apps Docs: https://learn.microsoft.com/en-us/power-apps/