A secure web application for storing, managing, and visualizing team members' skillsets and strengths. This application allows team members to complete self-assessment forms and enables team leaders to view aggregated skill data.

• 🔐 Microsoft Entra ID Authentication - Secure single sign-on
• 📋 Dynamic Assessment Forms - Admin-uploaded skill assessments
• 📊 Skill Data Visualization - Individual and team skill dashboards
• 👥 Team Management - Role-based access control
• ☁️ Azure Integration - Cloud-hosted with Azure services
• 📱 Responsive Design - Works on desktop, tablet, and mobile devices

• Python 3.12+
• uv (Python package manager)

1. Clone the repository

   git clone https://github.com/robpitcher/teamskill-demo.git
   cd teamskill-demo

2. Create Python virtual environment

   uv venv

3. Automated Setup (Linux/macOS)

   # Make the setup script executable
   chmod +x setup.sh
   
   # Run the setup script
   ./setup.sh

4. Manual Setup

   # Install Python dependencies
   uv sync

5. Start the development server

   cd backend
   uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

6. Access the application

   • Open your browser to: http://localhost:8000
   • Health check endpoint: http://localhost:8000/health

teamskill-demo/
├── backend/                   # Python FastAPI application
│   ├── app/                   # Application code
│   │   ├── __init__.py
│   │   └── main.py           # FastAPI app with routes
│   ├── static/               # CSS, JS, images
│   │   └── style.css         # Application styling
│   ├── templates/            # Jinja2 HTML templates
│   │   └── index.html        # Home page template
│   └── tests/                # Test suite
├── docs/                     # Documentation
│   └── prd.md                # Product Requirements Document
├── frontend/                 # React frontend (placeholder)
│   └── README.md             # Frontend documentation
├── pyproject.toml            # Python project configuration and dependencies
├── uv.lock                   # Dependency lock file for reproducible builds
├── setup.sh                  # Setup automation script
└── README.md                 # This file

The backend uses FastAPI with the following key components:

• FastAPI: Modern ASGI web framework for building APIs
• Uvicorn: ASGI server for development and production
• Jinja2: Template engine for HTML rendering (temporary until React frontend)
• Static files: CSS styling for the basic UI

Templates are located in backend/templates/ and use Jinja2 syntax:

<h1>{{ title }}</h1>
<p>{{ description }}</p>

@app.get("/new-endpoint")
async def new_endpoint():
    return {"message": "Hello from new endpoint"}

Current backend dependencies:

• fastapi==0.104.1
• uvicorn==0.24.0
• jinja2==3.1.2
• python-multipart==0.0.6

The project includes comprehensive unit tests for all existing functionality.

cd backend
uv run python -m pytest tests/ -v

Current tests cover:

• ✅ Route endpoints: Home page (/) and health check (/health)
• ✅ Static file serving: CSS files and error handling
• ✅ Template rendering: Context variables and HTML structure
• ✅ HTTP methods: Proper method validation and error responses

For detailed testing documentation, see backend/tests/README.md.

GitHub Actions automatically runs all tests on pull requests to the main branch. The CI workflow:

• Sets up Python 3.12 environment
• Installs dependencies
• Runs pytest with verbose output
• Fails if any tests fail

The project uses MegaLinter to ensure code quality and consistency across Python, HTML, and CSS files.

MegaLinter automatically runs on all pull requests to the main branch.

To run MegaLinter locally using Docker:

# Run MegaLinter on all files
docker run --rm -v $(pwd):/tmp/lint oxsecurity/megalinter:v7

# Run MegaLinter on changed files only (faster)
docker run --rm -v $(pwd):/tmp/lint oxsecurity/megalinter:v7 --env VALIDATE_ALL_CODEBASE=false

The linting configuration is defined in .mega-linter.yml in the repository root. The configuration:

• Runs all linters
• Applys some fixes automatically

For more information about MegaLinter, visit the official documentation.

The frontend is planned to be built with:

• React.js: Modern UI library
• TypeScript: Type-safe JavaScript
• Vite: Fast build tool
• Azure Static Web Apps: Hosting platform

Refer to frontend/README.md for more details on the planned frontend implementation.

• Backend: http://localhost:8000

This application is designed for Azure hosting:

• Azure App Service: For backend hosting
• Azure Static Web Apps: For React frontend hosting
• Azure SQL/Cosmos DB: For data storage
• Azure Blob Storage: For assessment file uploads
• Microsoft Entra ID: For secure authentication
• Azure Monitor/App Insights: For logging and diagnostics

The following environment variables will be used in future versions:

1. Ensure Python virtual environment is activated
2. Install dependencies: uv sync
3. Run the development server: uv run uvicorn app.main:app --reload
4. Make your changes
5. Update documentation as needed

• Authentication not implemented yet (planned: Microsoft Entra ID)
• No sensitive data storage in current version
• Future versions will include proper RBAC and data encryption

This project is for demonstration purposes.

Current Status: 🚧 Early Development - Basic scaffold implemented

Last Updated: August 23, 2025

For detailed requirements and planned features, see Product Requirements Document.