/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Frontend Architecture

Keywords on this page
WordMeaningExample
SPAOne web page that redraws itselfThe whole app
ComposableA reusable piece of stateful Vue logicuseTheme
StoreState shared across pagesstores/domains
TresJSVue components for three.js, the 3D libraryTresCanvas
TSLthree.js shader language, runs on the GPUghost style
Instanced meshOne drawing call for many copiesAll rooms
SpriteA flat image that always faces the cameraA sensor pin

Package: frontend/ · Stack: Vue 3 / Vite / Tailwind CSS v4 / TresJS / vue-i18n

One app, organised by feature first, by job second: a folder per page, and inside it a folder per job.

flowchart LR
    S["Socket.IO client"] --> C["Composables and stores"]
    A["useApi: REST"] --> C
    C --> V["Views"]
    V --> P["Components"]
    U["utils: pure logic, unit tested"] --> C

Layout

PathHolds
views/<feature>/One routed page per feature: homepage, dashboard, digital-twin, domains, administration, authentication
components/<feature>/<role>/That page’s parts, e.g. dashboard/{header,kpi,table,charts}, digital-twin/{scene,controls,buildings,rooms,modals}
components/commons/base (buttons, badges, cards), forms, overlays (modal, popover), layout (app shell, nav bar), navigation, account, chat, notifications, data (pagination, clock)
composables/<feature>/Stateful logic, in the feature that owns it; shared ones (useApi, useTheme, chat, live sensor data) in commons/
utils/<feature>/Pure logic, unit-tested beside the file it covers
types/<feature>/Types only: wire shapes and component-facing types, no runtime code except enums
stores/<feature>/Pinia stores: authentication, domains, digital-twin (buildings), commons (notifications, sensor data)
services/socket.tsThe one Socket.IO client, shared by every feature
router/routes.tsEvery path, read by the router and the nav links

Design System

Colours are Material 3 roles, declared once in src/assets/main.css:

TokenUse
text-display-clock … text-label-headerType scale; Inter, tabular figures
surface-cardCard surface: large radius, shadow-soft, faint ring; no drawn border
shadow-soft, shadow-liftResting cards; popovers, modals and hovered cards
fieldEvery text input and select
Tone (utils/commons/tone.ts)Semantic colour a helper returns (statusTone, getRoleMeta, SEVERITY_TONE); BaseBadge and StatusDot map it to roles

3D Twin Scene

Sensor Editor

Who owns what. Telemetry owns a sensor (id, name, device kind, room); digital-twin owns only its position. The frontend joins the two lists on sensorId (joinSensorsWithPlacements, utils/digital-twin/sensors.ts); a placement whose sensor is gone is dropped, never drawn.

What the scene draws.

Devices mode. (Mode.Devices, toolbar “Show devices”)

Placing a point sensor.

Tests. frontend/e2e/sensors.spec.ts (just test frontend-e2e) drives the real UI with telemetry and twin stubbed by Playwright routes, including a click in the canvas to place an outdoor sensor, and asserts the two batches the app sent. The services have their own suites, so stubbing them keeps the browser test about the editor.

Dashboard

Shell

Popovers dismiss themselves

PopoverMenu closes on a pointer press outside it or on Escape (useDismiss). A popover inside a clickable card still needs @click.stop on the menu, or the card handles the click too.