A comprehensive calendar management and timesheet automation system for Microsoft 365 users. Admin Assistant automates calendar archiving, appointment categorization, overlap resolution, privacy management, and timesheet generation for professional service providers.
Current Status: Core infrastructure complete (80%), implementing timesheet generation and travel management features.
- ✅ Infrastructure Complete: Microsoft Graph integration, database schema, CLI interface, testing framework
- ✅ Phase 1 Workflows: Calendar archiving, category processing, overlap resolution, privacy automation
- 🔄 In Progress: PDF timesheet generation, travel detection, Xero integration
- 📋 Next: Enhanced web interface, email notifications, client communications
For detailed status and implementation roadmap, see Consolidated Action Plan.
- Consolidated Action Plan - Current status and implementation roadmap
- Current Implementation Status - Detailed feature completion status
- CLI Command Structure - Complete CLI reference
- System Architecture - Technical architecture overview
docs/
├── 1-requirements/ # System requirements and use cases
├── 2-design/ # Architecture and design documents
├── 3-implementation/ # Implementation guides
├── 4-testing/ # Test cases and plans
├── guidelines/ # Development guidelines
└── CAP-001-Consolidated-Action-Plan.md # Main project roadmap
The Admin Assistant provides a powerful CLI for managing calendars, archives, categories, and timesheet operations.
# Set user environment variable to avoid repeating --user
export ADMIN_ASSISTANT_USER=123
# Login to Microsoft 365
admin-assistant login msgraph --user 123
# Archive calendar events
admin-assistant calendar archive --archive-config 1 --date "last 7 days"
# List categories
admin-assistant category list
# Generate timesheet (coming soon)
admin-assistant timesheet export --output PDF# Archive calendar events using a specific config
admin-assistant calendar archive "Work Archive" --user <USER_ID> --date "last week"
# List calendars for user
admin-assistant calendar list --user <USER_ID> --store msgraph
# Create new calendar
admin-assistant calendar create --user <USER_ID> --store msgraph --name "Archive Calendar"
# Analyze overlapping appointments
admin-assistant calendar analyze-overlaps --user <USER_ID> --start-date "2024-01-01"
# Backup calendar to file
admin-assistant calendar backup --user <USER_ID> --source "Work Calendar" --destination "/backups/work.csv" --format csv
# Backup calendar to another calendar
admin-assistant calendar backup --user <USER_ID> --source "Work Calendar" --destination "Work Backup" --format local_calendar# List categories
admin-assistant category list --user <USER_ID> --store local
# Add new category
admin-assistant category add --user <USER_ID> --name "Client Work" --description "Billable client work"
# Validate appointment categories
admin-assistant category validate --user <USER_ID> --start-date "2024-01-01" --stats# List all archive configs for a user
admin-assistant config calendar archive list --user <USER_ID>
# Create a new archive config (interactive prompts for missing fields)
admin-assistant config calendar archive create --user <USER_ID>
# Create a new archive config (all options provided)
admin-assistant config calendar archive create --user <USER_ID> --name "Work Archive" --source-uri "msgraph://source" --dest-uri "msgraph://dest" --timezone "Europe/London" --active
# Activate/deactivate/delete a config
admin-assistant config calendar archive activate --user <USER_ID> --config-id <CONFIG_ID>
admin-assistant config calendar archive deactivate --user <USER_ID> --config-id <CONFIG_ID>
admin-assistant config calendar archive delete --user <USER_ID> --config-id <CONFIG_ID># Login to Microsoft 365
admin-assistant login msgraph --user <USER_ID>
# Logout
admin-assistant login logout --user <USER_ID># Schedule automatic archiving
admin-assistant jobs schedule --user <USER_ID> --config-id <CONFIG_ID> --frequency daily
# Check job status
admin-assistant jobs status --user <USER_ID>
# Trigger manual archive
admin-assistant jobs trigger --user <USER_ID> --config <CONFIG_ID>
# Schedule automatic backup
admin-assistant jobs schedule-backup --user <USER_ID> --source "Work Calendar" --destination "/backups/work.csv" --type daily --hour 2
# Check backup job status
admin-assistant jobs backup-status --user <USER_ID># Restore appointments from audit logs (failed operations)
admin-assistant restore from-audit-logs --user <USER_ID> --start-date "2025-05-29" --end-date "2025-06-06"
# Restore from backup calendars
admin-assistant restore from-backup-calendars --user <USER_ID> --source "Recovered" "Recovered Missing" --destination "Consolidated Recovery"
# Backup a calendar to file
admin-assistant restore backup-calendar --user <USER_ID> --source "Main Calendar" --destination "backup.csv" --format csv
# List restoration configurations
admin-assistant restore list-configs --user <USER_ID>
# Dry run (preview without making changes)
admin-assistant restore from-audit-logs --dry-runFor complete CLI documentation, see CLI Command Structure.
Admin Assistant is built as a modular, service-oriented application with:
- Core Layer: Business logic, domain models, and data access abstractions
- Web Interface: Flask-based web UI with Bootstrap and Jinja2
- CLI Interface: Typer-based command-line interface for automation
- Integration Layer: Microsoft Graph, Google Directions, Xero, OpenAI APIs
- Data Layer: SQLAlchemy with PostgreSQL/SQLite support
- Background Processing: Flask-APScheduler for automated tasks
Key architectural patterns:
- Repository pattern for data access abstraction
- Service layer for business logic
- Orchestrator pattern for complex workflows
- Generic entity associations for extensibility
See System Architecture for detailed technical documentation.
- Python 3.8+
- Microsoft 365 account with calendar access
- Virtual environment (recommended)
# Clone the repository
git clone https://github.com/bcherrington/admin-assistant.git
cd admin-assistant
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Initialize database
python -m flask db upgrade
# Login to Microsoft 365
admin-assistant login msgraph --user <YOUR_USER_ID>- Create an archive configuration:
admin-assistant config calendar archive create --user <USER_ID> - Test archiving:
admin-assistant calendar archive "Work Archive" --user <USER_ID> --date "yesterday" - Validate categories:
admin-assistant category validate --user <USER_ID> --stats
# Activate virtual environment
source .venv/bin/activate
# Run core application tests (default - excludes utility tests)
python scripts/dev_cli.py test all
# Run all tests including utilities
python scripts/dev_cli.py test all-inclusive
# Run only utility/development infrastructure tests
python scripts/dev_cli.py test utilities
# Run with coverage
python scripts/dev_cli.py test all --coverage
# Run specific test categories
python scripts/dev_cli.py test unit
python scripts/dev_cli.py test integration- Core Tests: Application logic, services, repositories (default runs)
- Utility Tests: Testing infrastructure, development tools (excluded by default)
- Integration Tests: End-to-end workflows and system integration
- Follow the patterns established in
core/directory - Use repository pattern for data access
- Add comprehensive tests for new features
- Update documentation for API changes
See Development Guidelines for detailed coding standards.
- Calendar Archiving: Automated daily archiving with overlap detection
- Appointment Restoration: Generic restoration from audit logs, backup calendars, and export files
- Calendar Backup: Backup calendars to various formats (CSV, JSON, ICS) or other calendars
- Category Management: Appointment categorization with validation
- Privacy Automation: Automatic privacy marking and out-of-office detection
- Overlap Resolution: Smart detection and resolution of conflicting appointments
- CLI Interface: Comprehensive command-line tools with restoration commands
- Background Jobs: Scheduled archiving and maintenance tasks
- Audit Logging: Complete audit trail for all operations with reversible operations support
- PDF Timesheet Generation: Extract and format billable hours
- Travel Detection: Automatic travel appointment suggestions
- Xero Integration: Invoice generation with timesheet attachments
- Enhanced Web Interface: Improved UI for overlap resolution
- Email Notifications: Client communications and status updates
- Advanced Reporting: Analytics and insights dashboard
This project follows the Solo-Developer-AI-Process framework for AI-assisted development.
For implementation tasks, see AI Implementation Prompts for ready-to-use development prompts.
This project is licensed under the MIT License - see the LICENSE file for details.
- Getting Started Guide - Start here for new users
- CLI Reference - Complete command reference
- Troubleshooting Guide - Common issues and solutions
- Current Implementation Status - Single source of truth for project status
- Consolidated Action Plan - Development roadmap and priorities
- Solo Developer AI Process - Development framework
- Software Requirements Specification - Complete requirements
- System Architecture - System design
- Database Schema - Current database structure
- CLI Command Structure - Command organization
- Test Plan - Testing strategy
- Requirements Traceability - Implementation tracking
- Issues: GitHub Issues
- Project Board: GitHub Projects