MSP C2 - Ticketing and Billing System MVP

An end-to-end solution for managing tickets, time tracking, inventory, invoicing, and user management.

Features

• Ticket Management: Create, assign, and track tickets through resolution
• Time Tracking: Log time spent on tickets with detailed notes
• Inventory Management: Track parts, licenses, and services with stock levels
• Invoicing: Generate invoices from tickets with time and parts usage
• User Management: Admin-only user creation, modification, and role assignment
• Dashboard: Overview with key metrics (open tickets, overdue SLA, unpaid invoices)
• RBAC System: Role-based access control (admin, tech, billing, read_only)
• Audit Logging: Track all changes made to entities
• Webhook Integration: Send automation events on entity changes

Prerequisites

• Docker and Docker Compose
• Node.js (for development)

Setup Instructions

Quick Start with Docker (Development)

# Copy environment variables
cp .env.example .env

# Start the full stack
docker compose up --build

The application will be available at:

• Frontend: http://localhost:3147
• Backend API: http://localhost:7437
• Database: localhost:5439

Production Release Deployment

For production or self-contained deployment (no bind mounts):

# Use the release configuration
./scripts/release.sh

This creates a self-contained deployment with:

• Production-optimized Docker images (multi-stage builds)
• No bind mounts (all code baked into images)
• Named volumes for persistent data only
• Environment-driven configuration

See RELEASE.md for detailed deployment guide.

Development Setup

For development, you can run individual services:

# Terminal 1: Start database
docker compose up db

# Terminal 2: Start backend (from backend directory)
cd backend
pip install -r requirements.txt

# Install dev dependencies for linting, type checking, and testing
pip install -r requirements-dev.txt

# Or install both at once:
pip install -r requirements.txt -r requirements-dev.txt

# Run database migrations (required on first setup and after schema changes)
alembic upgrade head
# Or use the helper script:
# ./scripts/migrate.sh

uvicorn main:app --reload

# Terminal 3: Start frontend (from frontend directory)
cd frontend
npm install
npm run dev

Database Migrations

This project uses Alembic for database migrations. Migrations track schema changes and ensure consistency across environments.

Running Migrations

cd backend

# Apply all pending migrations
alembic upgrade head

# Or use the helper script
./scripts/migrate.sh

# Check migration status
./scripts/migrate.sh status

Creating New Migrations

When you modify SQLAlchemy models, create a migration:

cd backend

# Auto-generate migration from model changes
alembic revision --autogenerate -m "Add phone column to users"

# Or use the helper script
./scripts/migrate.sh create "Add phone column to users"

# Review the generated migration in alembic/versions/
# Then apply it
alembic upgrade head

Migration Commands

# View all commands
./scripts/migrate.sh help

# Common commands
./scripts/migrate.sh upgrade     # Apply migrations (default)
./scripts/migrate.sh downgrade   # Rollback one migration
./scripts/migrate.sh reset       # Reset database (careful!)
./scripts/migrate.sh status      # Check current status

Seeding Demo Data

To create demo data and an initial admin user:

# After starting the services and running migrations
docker compose exec backend python scripts/seed_demo_data.py

Automated Testing

The project includes comprehensive automated testing infrastructure:

Run Tests Locally

# Run all tests
./scripts/run-tests.sh

# Or use Python version (cross-platform)
python scripts/run_tests.py

# Run specific test types
./scripts/run-tests.sh backend        # Backend tests only
./scripts/run-tests.sh frontend       # Frontend tests only
./scripts/run-tests.sh integration    # Integration tests
./scripts/run-tests.sh security       # Security tests
./scripts/run-tests.sh performance    # Performance tests

Run Tests in Docker

# Full test suite in isolated environment
docker compose -f docker-compose.test.yml up --abort-on-container-exit

# View test reports
docker compose -f docker-compose.test.yml --profile reports up
# Open http://localhost:8080

Test Coverage

• Backend: 135+ tests with coverage reporting
• Frontend: Full test suite with coverage
• Integration: End-to-end workflow tests
• Security: Automated security scanning
• Performance: Load and benchmark tests

View detailed testing documentation: docs/AUTOMATED_TESTING.md

CI/CD Pipeline

This project uses Forgejo (self-hosted Git service) for CI/CD:

Workflows

Workflow	File	Trigger	Purpose
Full CI	.forgejo/workflows/ci.yml	Push, PR	Lint, test, security scan, build
Quick Test	.forgejo/workflows/quick-test.yml	Push, PR	Fast test validation

Pipeline Stages

1. Lint & Format - Black, flake8, ESLint
2. Test - Backend pytest, frontend tests
3. Security - Bandit security scan
4. Build - Docker image build
5. Deploy - Production deployment (manual)

Local Linting

Run the same checks locally before pushing:

# Backend linting
cd backend
black --check .
flake8 . --exclude=alembic,tests

# Frontend linting
cd frontend
npm run lint

CI Status

Check pipeline status in your Forgejo instance under Actions.

Default Demo Credentials

Email: admin@example.com Password: admin123

MVP Walkthrough Steps

Basic Workflow

1. Login: Access the system with demo credentials
2. Dashboard: View key metrics and recent activity
3. Create Customer: Add a new customer organization
4. Create Contacts: Add contacts for the customer
5. Add Inventory: Add parts, licenses, or services to inventory
6. Create Ticket: Open a new ticket for a customer
7. Log Time & Parts: Add time entries and part usage to the ticket
8. Generate Invoice: Create an invoice from the ticket
9. Mark Paid: Update invoice status to paid

Admin Workflow

1. Access Dashboard: View system-wide metrics at a glance
2. Manage Users: Create, edit, and delete users (Admin only)
   • Navigate to Users page from sidebar
   • Create new users with appropriate roles
   • Reset passwords when needed
3. Logout: Securely log out when finished

API Overview

The backend provides a REST API with the following endpoints:

Core Endpoints (Implemented)

• /api/v1/auth/ - Authentication routes (login, logout, me)
• /api/v1/users/ - User management (admin-only CRUD operations)
• /api/v1/customers/ - Customer organizations and contacts
• /api/v1/catalog/ - Inventory and stock management
• /api/v1/tickets/ - Ticket management
• /api/v1/invoices/ - Invoice creation and management
• /api/v1/hooks/ - Webhook configurations and testing
• /api/v1/dashboard/ - Dashboard statistics and metrics
• /api/v1/health - Health check

All endpoints respect the role-based access controls configured in the system.

Network Topology Module

The network topology module models customer network infrastructure through three entity types:

NetworkNode — devices or endpoints in the network:

Field	Type	Description
id	int	Primary key
customer_id	int	FK to customer organization
asset_id	int?	FK to customer asset (optional)
label	str	Node display name
node_type	str?	core, distribution, access, endpoint
x_pos, y_pos	float?	Visualization coordinates

NetworkLink — connections between nodes:

Field	Type	Description
id	int	Primary key
source_node_id	int	FK to source NetworkNode
target_node_id	int	FK to target NetworkNode
link_type	str?	ethernet, wifi, fiber, vpn
bandwidth_mbps	int?	Link bandwidth
vlan_id	int?	Associated VLAN

Subnet — IP subnets assigned to a customer:

Field	Type	Description
id	int	Primary key
customer_id	int	FK to customer organization
network_address	str	e.g. 192.168.1.0
cidr	int	e.g. 24
vlan_id	int?	Associated VLAN
description	str?	Human-readable description
notes	text?	Free-form notes

CRUD Operations (backend/crud/network.py):

• Nodes: get_nodes(customer_id), create_node(db, node), update_node(db, node_id, node), delete_node(db, node_id)
• Links: get_links(db, customer_id), create_link(db, link), delete_link(db, link_id)
• Subnets: get_subnets(db, customer_id), create_subnet(db, subnet), update_subnet(db, subnet_id, subnet), delete_subnet(db, subnet_id)

API Routers:

• GET/POST /api/v1/network/{customer_id}/nodes — list / create nodes
• GET/POST /api/v1/network/{customer_id}/links — list / create links
• GET/POST /api/v1/subnets/{customer_id} — list / create subnets

All network endpoints require ADMIN, TECH, or READ_ONLY roles for reads, and ADMIN or TECH for writes.

Docs

API & Architecture

• docs/api_contract.md - Canonical API contract
• docs/api_overview.md - Detailed API endpoints documentation
• docs/api_quick_reference.md - Quick API reference guide
• docs/architecture.md - System architecture overview
• docs/data_model.md - Database schema documentation

Operations

• docs/DEPLOYMENT.md - Production deployment guide
• docs/DATABASE_MIGRATIONS.md - Alembic migration guide
• docs/OPERATIONS_RUNBOOK.md - Operations procedures
• docs/OBSERVABILITY.md - Monitoring and logging
• docs/DISASTER_RECOVERY.md - Disaster recovery procedures
• docs/backup_restore.md - Backup/restore drill

Development

• docs/IMPLEMENTATION_STATUS.md - Feature implementation status
• docs/AUTOMATED_TESTING.md - Testing documentation
• docs/error_handling.md - Error envelope + middleware behavior
• docs/performance.md - Baseline performance measurements
• ROADMAP.md - Product roadmap and future plans
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history

Archived

• docs/archive/ - Historical documentation snapshots

For AI Assistants

• AGENT_QUICKSTART.md - Quick reference guide for agentic assistants working on this project

Project Structure

/
├── docker-compose.yml        # Container orchestration
├── .env.example             # Environment variables template
├── README.md               # This file
├── test_harness.py         # Comprehensive test suite runner
├── validate_mvp.py         # MVP validation script
├── TEST_HARNESS_*.md       # Test documentation
├── backend/                # FastAPI backend application
│   ├── main.py             # Application entry point
│   ├── models/             # SQLAlchemy models
│   ├── schemas/            # Pydantic schemas
│   ├── api/                # API routes
│   ├── crud/               # Database CRUD operations
│   ├── services/           # Business logic services
│   ├── core/               # Core utilities (config, database)
│   ├── utils/              # Helper utilities
│   ├── tests/              # Test suite (17 test files)
│   └── requirements.txt    # Python dependencies
├── frontend/               # React frontend application
│   ├── src/                # Source code
│   │   ├── pages/          # Page components
│   │   ├── components/     # Reusable components
│   │   ├── hooks/          # Custom React hooks
│   │   └── services/       # API service layer
│   ├── package.json        # Node dependencies
│   └── vite.config.js      # Vite configuration
└── docs/                   # Documentation
    ├── architecture.md     # System architecture overview
    ├── data_model.md       # Database schema documentation
    ├── api_overview.md     # API endpoints documentation
    ├── api_contract.md     # API contract specification
    ├── error_handling.md   # Error handling documentation
    ├── monitoring.md       # Health checks and monitoring
    ├── performance.md      # Performance baseline
    └── threat_notes.md     # Security considerations