incident.altavoce.tech

[!WARNING] Deployment Status: This incident management system has not yet been deployed in production. Its current usage is strictly limited to local development and testing environments.

Overview

incident.altavoce.tech is the incident management system dedicated to Alta Voce's artificial intelligence services.

Features

  • Automatic incident detection
  • Classification and prioritization
  • Real-time notification
  • Resolution tracking
  • Post-incident analysis

Architecture

The system integrates with the following services:

  • ia-altavoce.tech : Main source of incidents
  • Monitoring Stack : Metrics and alerts
  • Notification Service : Alert delivery (email, Slack, SMS)
  • Knowledge Base : Database of resolved incidents

Technical Specifications

The system is built on a highly reactive, high-performance architecture to ensure immediate capture, queuing, and routing of critical system anomalies:

  • Main Framework : Laravel 13 / PHP 8.3
  • Frontend Engine : Livewire v4 (dynamic real-time reactivity without heavy client-side Javascript)
  • Event Broadcasting : Laravel Reverb (native WebSockets for streaming live alerts to the operations dashboard)
  • Local Database : SQLite (database/database.sqlite) for frictionless local development, MySQL in production
  • Log Streaming : Laravel Pail (live, filtered tailing of logs directly in your development terminal)

Local Installation & Startup Guide

To install and run the incident.alta-voce.tech project locally, follow this standard engineering workflow:

1. Automatic Environment Provisioning (Setup Script)

The repository includes a dedicated Composer script to fully bootstrap and configure the project in a single command:

composer run setup

This script automates: composer install, copying .env.example to .env, generating the application security key (artisan key:generate), applying SQL database schema migrations, installing npm packages, and building assets (npm run build).

2. Multi-Process Development Server (Concurrently)

In local development, multiple background processes must run in parallel (the HTTP server, the queue job listeners, the live Pail log tailer, and Vite's hot-reloading dev server).

To eliminate the need for running four separate terminal instances, orchestrate all processes simultaneously with:

composer run dev

This command uses concurrently to spawn and synchronize:

  • server : The local web server (php artisan serve)
  • queue : The background job worker (php artisan queue:listen)
  • logs : The real-time log tailer (php artisan pail)
  • vite : Vite's asset compiler and hot reloader (npm run dev)

Access

  • URL : https://incident.altavoce.tech
  • Dashboard : https://incident.altavoce.tech/dashboard
  • API : https://incident.altavoce.tech/api

Incident Management Flow

1. Detection

Incidents are detected automatically through:

  • System metrics monitoring
  • Error log analysis
  • User reports

2. Classification

Each incident is classified by:

  • Severity : Critical, High, Medium, Low
  • Category : Performance, Availability, Quality, Security
  • Impact : Affected users, Impacted services

3. Notification

Notifications are sent based on severity:

  • Critical : Immediate (all channels)
  • High : Immediate (email + Slack)
  • Medium/Low : Daily (email)

4. Resolution

Tracking includes:

  • Automatic or manual assignment
  • Resolution time tracking
  • Action documentation

Emergency Procedures

Critical Incident

  1. Immediate alert to on-call team
  2. Activate emergency Slack channel
  3. Communicate to stakeholders
  4. Resolve within 15 minutes

High Incident

  1. Notify concerned team
  2. Assess impact
  3. Plan resolution
  4. Resolve within 1 hour

API Integration

Create an Incident

curl -X POST https://incident.altavoce.tech/api/v1/incidents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "title": "AI service unavailable",
    "severity": "critical",
    "description": "ia-altavoce.tech service is not responding",
    "service": "ia-altavoce.tech"
  }'

View Incidents

curl -H "Authorization: Bearer <token>" \
  https://incident.altavoce.tech/api/v1/incidents?status=open

Best Practices

  • Document every incident for continuous learning
  • Analyze root causes to prevent recurrences
  • Update procedures regularly
  • Train team on emergency protocols

Support

For any questions about the incident management system, contact the DevOps team or refer to the internal documentation.