Skip to main content

Web Console Overview

The TkushPatch Web Administration Console (ota-web-console) is a Next.js 15 application (App Router, React 19, TypeScript) acting as the graphical Control Plane to manage mobile release lifecycles, OTA patches (compressed binary diff), rollout strategies, RBAC governance, and fleet observability.

Architecture and Tech Stack​

The web console acts both as an operator user interface and as a BFF (Backend-For-Frontend) gateway to the TkushPatch Server server (ota-server, port 8080 by default via the OTA_BACKEND_URL environment variable).

LayerTechnology / ComponentPrimary Role
UI FrameworkNext.js 15 (src/app/)App Router navigation, Server/Client Components, and proxy API routes (src/app/api/)
AuthenticationAuthProvider (src/lib/auth/AuthContext.tsx)Operator session (localStorage + HTTP cookies), inactivity lock (IdleTimer)
Access Controlmiddleware.ts & RoleGuard.tsx5-role RBAC enforcement across routes and action buttons
Project ContextProjectProvider (src/lib/project/ProjectContext.tsx)Active application state (selectedAppId) and automatic release discovery
Visual ThemeThemeProvider (src/components/layout/ThemeProvider.tsx)Dynamic toggle between light (light) and dark (dark) themes
InternationalizationI18nProvider (src/lib/i18n/I18nProvider.tsx)Instant client-side French (fr) / English (en) translation

Layout Structure (AppLayoutShell)​

All authenticated pages are wrapped inside the AppLayoutShell component (src/components/layout/AppLayoutShell.tsx), which orchestrates the global layout (excluding public routes /login, /register, /forgot-password, and /cli/login):

User Interface Structure
  • Top Header: Organization switcher, system alerts, theme toggle (dark/light), and user account profile.
  • Sidebar: Quick navigation across Applications, Releases, Patches, Approvals, Fleet Devices, and Settings.
  • Main Viewport: Operational dashboards, live rollout charts, and management action controls.

The Sidebar component (src/components/layout/Sidebar.tsx) dynamically filters visible menu items according to the signed-in operator's RBAC role using the hasAccessToRoute(role, href) function defined in src/lib/auth/roles.ts.

Menu items are grouped into three main sections:

1. Operations and Deployment​

  • Applications (/apps): Catalog of all mobile applications in the organization and project creation wizard.
  • Overview (/): Global executive dashboard (fleet KPIs, latest releases, recent audit events).
  • Releases & Patches (/releases): Consolidated master registry of all binary versions and patch publication modal.
  • Store Catalog (/catalog): Store version governance (Apple App Store / Google Play) and IN_STORE_REVIEW shield.
  • Rollout & Geo (/rollout): Progressive Canary control (0% to 100%), ISO-3166-1 country targeting, and network/criticality strategies.
  • Approvals (4-Eyes) (/approvals): STAGED quarantine queue and digital signature cryptographic signing (APPROVED_AND_SIGNED).
  • Dynamic Assets (/assets): Over-the-air CDN management for images, banners, and JSON configuration bundles.

2. Observability and Support​

  • Crashes & Symbols (/symbols): Storage for \.symbols Dart/C++ files and interactive stacktrace deobfuscation console.
  • Mobile Telemetry (/telemetry): Real-time stream of SDK events (patch_install_success, patch_install_failure) and automatic Circuit-Breaker status.
  • Customer Support (L2/L3) (/support): #8CAR short support code lookup, device diagnostics, QA Whitelist (isWhitelistedQA), and rollback acknowledgment.

3. Governance and Security​

  • Teams & Access (/teams): Collaborator management, SMTP invitations, and 5-role RBAC assignment.
  • Security Policies (/policies): Configuration of the Four-Eyes principle, Anti-Bomb quotas, HMAC expiration, and TLS certificate pins.
  • Audit Trail (/audit): Immutable traceability log with CSV export and signed PDF report generation.
  • System Health (/health): cryptographic signing engine / local-rsa status, disk usage, L1/L2 cache metrics, and Day-2 deprecated artifact purge.
  • My Account (/account): Personal operator profile, visual preferences, and organization indicators.

Header (Header) and Breadcrumbs (HeaderBreadcrumb)​

The top header (src/components/layout/Header.tsx) provides cross-cutting controls:

  1. Dynamic Breadcrumbs (HeaderBreadcrumb.tsx): Displays the exact hierarchical path (e.g., Organization > Applications > com.sara.money > Releases > 3.28.5+99) with quick navigation links.
  2. Application Selector (ProjectSwitcher.tsx): Allows switching between mobile applications instantaneously or opening the CreateProjectModal.
  3. Quick Search Bar: Filters versions, application identifiers (app_id), or patch numbers.
  4. Backend Status Indicator: Real-time badge showing connectivity to the TkushPatch backend and signing engine.
  5. Locale and Theme Switchers: Direct toggle buttons for language (FR / EN) and theme (Light / Dark).

Project Switcher (ProjectSwitcher & ProjectContext)​

The ProjectSwitcher component (src/components/layout/ProjectSwitcher.tsx) relies on ProjectContext (src/lib/project/ProjectContext.tsx) to maintain the organization's application list:

  • Local Persistence: Projects are stored in localStorage under tks_projects_registry and the currently selected application under tks_selected_app_id.
  • Backend Auto-Discovery: On startup, ProjectContext queries /api/admin/v1/releases?tenant_id=... and automatically merges any appId found on the server into the local project registry.
  • Contextual Routing: When an operator views a sub-page under /apps/[appId]/* and switches applications in the ProjectSwitcher, the URL automatically navigates to the corresponding tab of the newly selected application.

Light / Dark Theme (ThemeProvider)​

The ThemeProvider component (src/components/layout/ThemeProvider.tsx) manages visual appearance:

  • Storage Key: localStorage.getItem("tks_theme") ("light" or "dark", defaulting to "light").
  • DOM Application: Toggles the dark CSS class on document.documentElement (html), enabling Tailwind CSS dark palettes (dark:bg-slate-900, etc.) without reloading the page.
  • Access: Available anytime from the Sun/Moon icon in the Header or from the /account page.

FR / EN Internationalization (I18nProvider)​

The I18nProvider engine (src/lib/i18n/I18nProvider.tsx) delivers a fully bilingual console:

  • Storage Key: localStorage.getItem("tks_locale") ("fr" by default, or "en").
  • Mechanism: Exposes the useI18n() hook providing { locale, setLocale, t } for structured keys (nav.*, header.*, common.*) alongside a DOM observer (MutationObserver + TreeWalker) that dynamically translates UI strings when the "en" locale is active.