Client Workspace & Dashboard (client-alta.alta-voce.tech)

Auto-generated Documentation Links

Frontend Auto-generated Reference : See the auto-generated Vue 3 component reference at docs/altacall/client-alta-frontend.md.

1. Architectural Role & Web Rendering

The client-alta application serves as the official client-facing interface provided to corporate partners. Structured as a premium, highly responsive Single Page Application (SPA) written in Vue 3, it allows call center supervisors and IT managers to remotely administer and monitor active voice processing systems.

Its core objectives include:

1. Real-Time Fleet Monitoring: Delivers at-a-glance statistics on how many agents/machines are online, have issues, or are running outdated software — auto-refreshing every 5 minutes.
2. Hardware & Software Diagnostics: Centrally logs workstation alerts and system anomalies compiled from client telemetry packets.
3. Operational Controls: Manages caller agent rosters, provisions access license keys, handles A/B testing campaign enrollments, and manages groups and organization settings.
4. Software Distribution: Provides a download center for all Alta Call desktop releases, with changelog and version history.

2. Project Directory Structure & Source Code (Vue 3)

The internal codebase layout adheres to modern Vue.js development standards:

graph TD
    A[main.js: Entry Point] --> B[App.vue: Root Layout]
    B --> C[router.js: Vue Router 4]
    B --> D[store.js: Vuex 4 State]
    B --> E[http.js: Axios Client]
    C --> F[Views / Pages]
    D --> G[Local Session Persistance: vuex-persist]
    E --> H[Laravel admin-alta REST API]

2.1. Application Entry Point (src/main.js)

Configures and mounts fundamental plugins onto the Vue application instance:

• Router & Store mounting: Registers Vue Router 4 and the central Vuex 4 state container.
• Internationalization (i18n): Bootstraps the vue-i18n translation engine (via createI18n). Handles dynamic translation loading (French/English) using compiled localization catalogs originally sourced from .po files via easygettext.
• Crash & Error Reporting: Hooks up the Sentry SDK to collect client-side JavaScript exceptions in real-time, forwarding them to DevOps pipelines for troubleshooting.

2.2. Navigation Router & Guards (src/router.js)

Declares the application route hierarchy and sets up authentication barriers:

• Nested Routing Layout: Implements a main wrapper template (views/dashboard/Base.vue) containing nested <router-view> blocks to dynamically render child sub-pages based on the active agent group URL (/dashboard/group/:id/...).
• Route Guards (beforeEach): Inspects metadata attributes on incoming destinations. If a route defines requiresAuth: true and the active Vuex session token is missing, the router redirects the browser to /login.
• Main Route Sections:
  • /dashboard/group/:group? — Main BI dashboard with sub-routes: users, machines, issues, abtests, labels, outdated-machines
  • /onboarding — New organization setup wizard
  • /organization — Organization settings, accounts, and groups management
  • /help — Help center, FAQ, API explorer, and setup guides
  • /downloads — Software version downloads
  • /account — Connected user profile settings
  • /feedback — Agent feedback submission

2.3. Vuex Central State Container (src/store.js)

State parameters are managed globally using Vuex 4, ensuring responsive view updates when switching groups or user profiles:

• State Properties:
  • user: Connected user profile properties (ID, name, email, role).
  • auth.accessToken: Active Sanctum API bearer token (opaque token, not JWT).
  • organization & groups: Business tenant linked to the connected administrator account and array of team departments.
  • selectedGroup / selectedGroupId: Currently selected department selected by the supervisor to filter dashboard charts.
• Store Persistence (vuex-persist): A middleware plugin automatically serializes core state keys (token, active group, user profile) using a custom AES-encrypted storage layer (powered by crypto-js), preventing sensitive tokens from being stored in plain text in localStorage.

2.4. HTTP Client Network Layer (src/http.js)

Handles outbound network traffic to the Laravel backend using a configured Axios wrapper:

• Request Interceptor: Reads the active bearer token from the Vuex store (auth.accessToken), injecting it automatically into request headers (Authorization: Bearer <token>). It also handles proactive token refresh when the token is about to expire.
• Response Interceptor (401 Expirations): Intercepts 401 Unauthorized responses returned by Laravel Sanctum (session expired on backend). If the user was active within the last 5 minutes, it attempts an automatic token refresh; otherwise, it clears the Vuex store and redirects the browser to /login.

2.5. Internationalization (src/language/)

Full bilingual support (English en_US and French fr_FR) managed via vue-i18n 9. Translations are extracted from source code using vue-gettext-extract (generating .pot/.po catalogs) and compiled to .i18n.js files with vue-gettext-compile. The active language is persisted in the encrypted local storage and can be switched from the user interface.

# Extract translation keys from source code
npm run i18n-extract

# Merge new keys into existing .po files
npm run i18n-merge

# Compile .po files to .i18n.js for the app
npm run i18n-compile

2.6. Error Monitoring (src/sentry.js)

The Sentry SDK is integrated for real-time client-side JavaScript error reporting. It is enabled automatically when the VITE_SENTRY_DSN environment variable is set.

2.7. Impersonation System

Admin users can impersonate any account from the portal. When impersonation is active, the Vuex store swaps the active user and token transparently — a visual widget (ImpersonateWidget.vue) indicates the impersonated session and allows the admin to stop impersonating at any time. All impersonation events are logged server-side in the impersonations table.

3. Application Routes Reference

All routes are defined in src/router.js. Authentication guard (requiresAuth: true) redirects unauthenticated users to /login.

4. Interactive User Workflows

The web dashboard is optimized to streamline administrative and IT workflows:

3.1. Tenant Onboarding Flow (/onboarding)

Guides newly registered client administrators through initial setups:

1. Consent Agreements: Review and signature of privacy terms and GDPR telemetry collection agreements.
2. First Group Creation: Define the name of the first operational department (e.g. "Outbound Call Team").
3. Key Provisioning: Automatically generates the first desktop client license handshake token.

3.2. Business Intelligence Charts

Renders interactive graphs capturing acoustic performance data compiled from daily users_summaries:

• Voice Pitch Modulation: Displays median F0 voice pitch before and after transformations, verifying vocal softness targets.
• Telemetry heartbeats: Tracks daily diagnostic payload frequencies to confirm software instances are running correctly on all workstations.

3.3. Mass Actions on Agent Rosters (Bulk Updates)

Inside /dashboard/group/:id/users, supervisors can execute bulk actions:

• Roster tables support individual and header multi-select checkboxes.
• A floating action bar slides up from the bottom of the viewport when multiple agents are checked.
• Operational Action: Allows managers to assign or clear skill-tags globally (e.g. enrolling 50 agents into "A/B Testing - Phase 1" in one click), avoiding editing agent profiles individually.

3.4. Workstation Issues Tracking

The /issues panel lists active workstations errors caught by backend diagnostics (mapped to machines_issues). Criticality badges help prioritize fixes:

• Critical (Red): Multiple background instances running inside the same Windows user session (MULTI_INSTANCES_SAMESESSION) or system audio pipeline initialization crashes (AUDIO_SETUP_FAILED).
• Medium (Orange): Workstation input microphone disconnected during active communications (AUDIO_DEVICE_LOST).
• Low (Blue): Postes running obsolete desktop software versions.

4. Local Development Environment Setup

1. Navigate to the client dashboard directory:

   cd client-alta.alta-voce.tech/client-alta
   
2. Install required Node.js package dependencies:

   npm install
   
3. Copy the environment configuration template and set the local API backend URL:

   cp .env.example .env
   # Edit .env and set the following variable: VUE_APP_API_URL=http://localhost:8000/
   
4. Start the local Vite development server:

   npm run dev
   
5. Open your web browser at the displayed local URL (typically http://localhost:5173).