Webservices and APIs

This section describes the architecture, development, and deployment of Alta Voce's web services.

General Architecture

Our web services are built around a Laravel monolith backend serving both the administration panel and the REST API, paired with a standalone Vue.js 3 SPA frontend:

Backend (Laravel Monolith) : Unified REST API, Filament admin dashboard, and scheduled CRON workloads
Frontend (Vue.js SPA) : Client-facing dashboard deployed as static files
Database : Centralized MySQL data storage (unified voimooo database)
Monitoring : Performance and health monitoring via Laravel Telescope

Development Repositories

Web services development is done in the following main repositories:

admin-alta.alta-voce.tech : Backend API and system administration interface deployed at https://admin-alta.alta-voce.tech/.
client-alta.alta-voce.tech : Client web interface deployed at https://client-alta.alta-voce.tech/.

Tech Stack

Backend (API & Administration)

Framework : Laravel 10 / PHP 8.1
Admin Panel : Filament Admin v3 (users, licenses, and devices management)
Database : MySQL (unified voimooo database)
Authentication : Laravel Sanctum (opaque tokens) and native secure session authentication
WebSockets : Laravel Reverb (for real-time streaming notifications)
Debugging Tool : Laravel Telescope
API Documentation : Scribe (automatically generated)

Frontend (Client Space)

Framework : Vue.js 3 (Composition API)
Build tool : Vite
Styling : TailwindCSS v3
State Management : Vuex 4 with AES-encrypted local persistence (vuex-persist + crypto-js)
Internationalization (i18n) : vue-i18n runtime, with translation extraction via Easygettext (compiled .po catalogs)
Error Monitoring : Sentry SDK (client-side exception reporting)

Hosting & Deployment

Hosting : Gandi Simple Hosting (Apache / PHP managed environment)
Deployment : Automated via GitHub Actions / GitLab CI runners (SFTP/Rsync file transfer + SSH post-deploy commands)
Scheduled Tasks : External HTTP cron scheduler (e.g. cron-job.org) calling secured /cron/* routes

Development Workflow

1. Backend Development Environment (API & Admin)

# Clone the backend repository
git clone https://gitlab.com/altaCall/admin-alta.alta-voce.tech.git
cd admin-alta.alta-voce.tech

# Install Composer and Node dependencies
composer install
npm install

# Set up local configurations
cp .env.example .env
# Edit the .env file with your local credentials (DB, mail, Sentry, etc.)

# Generate app key and run schema migrations
php artisan key:generate
php artisan migrate

# Start local artisan development server
php artisan serve

2. Frontend Development Environment (Client App)

# Clone the frontend repository
git clone https://gitlab.com/altaCall/client-alta.alta-voce.tech.git
cd client-alta.alta-voce.tech/client-alta

# Install dependencies
npm install

# Start local Vite development server
npm run dev

3. Testing and Code Quality Tools

# Run PHP unit and integration tests (Backend)
php artisan test

# Run PHP static analysis
vendor/bin/phpstan analyse

# Extract and compile translation keys (i18n — Frontend)
npm run i18n-extract
npm run i18n-compile

4. Deployment

Deployments are automated via CI/CD pipelines as soon as changes are merged into the production branch. See the full deployment runbook in DevOps & CI/CD.

Authentication

The API uses Laravel Sanctum opaque tokens (not JWT). After a successful login, the server returns a bearer token that must be included in all subsequent requests.

// 1. Authenticate and retrieve the bearer token
const response = await fetch('https://admin-alta.alta-voce.tech/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});
const { token } = await response.json();

// 2. Use the token in subsequent requests
const data = await fetch('https://admin-alta.alta-voce.tech/api/groups', {
  headers: { 'Authorization': `Bearer ${token}` }
});

[!NOTE] Tokens expire after 2 hours of inactivity. The frontend client (http.js) handles proactive refresh automatically when the token has less than 30 minutes remaining.

Desktop Client API (AltaCall Plugin)

The desktop plugin communicates with a dedicated set of routes under /api/altacall/, authenticated via a license key (sent as the X-License header or embedded in the payload):

Endpoint	Method	Description
`/api/altacall/license`	GET / POST	Validate the license key and retrieve group configuration
`/api/altacall/telemetry`	POST	Submit a periodic diagnostic telemetry payload
`/api/altacall/event`	POST	Notify the server of a device plug/unplug event
`/api/altacall/process`	POST	Declare a new running process instance
`/api/altacall/consent`	GET / POST	Read or update the agent's data collection consent
`/api/altacall/config`	GET	Retrieve the agent's active configuration
`/api/altacall/logs`	POST	Upload a diagnostic log bundle

Security Best Practices

All communications use HTTPS
API authentication uses Sanctum opaque tokens — never store them in plain localStorage (the frontend uses AES encryption via crypto-js)
Rate limiting is enforced on sensitive routes (throttle:sensitive on login/register/password-reset)
The user_request_logs table logs all API requests for audit and DDoS mitigation
License keys are validated server-side on every telemetry submission; revoked keys return HTTP 403 immediately

Troubleshooting

For common operational incidents (HTTP 500 after deploy, telemetry rejections, disk saturation, missing BI summaries), refer to the dedicated runbook:

👉 DevOps & CI/CD — Incident Troubleshooting Guide

For more technical information, refer to the specific documentation for each service in the sections above.