OUI_XFAB documentation

Architecture Guide

System Shape

OUI is a feature-first Vue modular monolith. The browser owns presentation, feature state, localization, and lifecycle orchestration. Equipment domain traffic uses WebSocket only. Static version retrieval and workstation identity are the two narrow same-origin HTTP exceptions.

app -> modules -> infrastructure
 |        |
 +--------+-------> shared

The interactive version is OUI Runtime Architecture.

Ownership

Owner	Responsibility
`src/app`	Composition, shell, router, global presentation state, bootstrap, and error handling
`src/modules/<feature>`	Complete vertical feature: API adapter, decoder/model, Pinia state, UI, and locale fragments
`src/infrastructure/websocket`	Browser transport, protocol codec, broker, event bus, connection lifecycle, and errors
`src/shared`	Reusable i18n, preferences, datetime, UI adapters, tokens, and primitives
`src/router`	Route definitions and router construction
`services/oui-access-service`	Loopback workstation identity, ticket redemption support, SQL adapter, and local admin CLIs
`tests/contracts`	Cross-feature protocol fixtures
`tests/e2e`	Production-preview browser workflows

Do not recreate generic roots such as src/components, src/services, src/stores, or src/types. A file belongs to the owner that controls its lifecycle and contract.

Public APIs

Code outside a feature imports its public src/modules/<feature>/index.ts entry point through @modules/<feature>. Deep imports into another module's api, model, state, ui, or i18n folders are prohibited. Public exports are treated as supported contracts, not convenience barrels.

The stable application contracts include @app, @infrastructure/websocket, @shared/ui, @shared/preferences, and the feature roots for configuration, administration, equipment, history, alarm history, dynamic popup, lot dispatch, version, and workstation identity.

Data Boundaries

Incoming WebSocket bodies remain unknown until the owning feature decoder validates them. Gateways translate protocol envelopes into domain models. Stores and components do not retain raw backend payload shapes and do not create sockets or call RequestBroker directly.

All command and event names come from src/constants/wsEvents.ts. The broker owns request registration, reply-event serialization, timeout quarantine, and pending-work rejection on connection teardown.

UI Foundation

The UI foundation is Vuetify 4 with Material Design Icons, Pinia 4, Vue Router 5, SCSS tokens, and synchronized light/dark themes. The single framework adapter is src/shared/ui/vuetify.ts; components use useAppToast and useAppConfirm instead of accessing framework notification services directly.

Architecture Enforcement

src/architecture/moduleBoundaries.spec.ts and the ESLint configuration enforce import direction, public-index usage, static analyzability, and UI ownership. Style ownership is pinned by fixtures so moving a styled component cannot silently change the global ownership model.