Skip to content

OVES UXI Architecture

This page is generated from the uxi-architecture.md blueprint in the repository. That file remains the canonical source; this is its rendered documentation form.

1. Purpose and Scope

This document defines the Unified Experience Interface (UXI) architecture for OVES. It is the baseline blueprint for:

  • Marketing and landing sites
  • Informatics dashboards (Battery Circulation, Fleet, operations, finance, etc.)
  • Transactional frontends (e.g. Odoo-backed applications)

All future OVES web properties must conform to this architecture so that:

  • Design philosophy, theme, and layout grammar are consistent
  • Content is the source of truth for behavior and composition
  • Developers do not inject new styling into applications

2. Core Principles

2.1 Content-Driven UX

  • Content = information + presentation styles.
  • The information and structure of a page are defined by content schemas (JSON / MDX).
  • The presentation styles and layout are defined by the UXI block library and shared design tokens.
  • Page behavior (which sections appear, in what order, with what semantics) must be fully derivable from content + UXI blocks.

2.2 Single Source of Truth for Design

  • OVES maintains a single design system (colors, typography, spacing, radii, shadows, etc.).
  • Only the UXI design authority may change this system.
  • Tailwind classes and styling logic live only inside the UXI layer and theme CSS.
  • Application developers must not add arbitrary Tailwind classes or raw CSS in feature code.

2.3 Reusable Blocks across All Sites

  • UXI exposes a stable set of blocks (Hero, FeatureGrid, StatsStrip, SplitSection, CTASection, form/list/table blocks, chart blocks, etc.).
  • Each block has a clear JSON schema for its props.
  • All sites – landing pages, dashboards, Odoo frontends – are built as compositions of these blocks.
  • New visual patterns must be added as new or extended UXI blocks, not ad-hoc components.

2.4 Separation of Concerns

  • Design & styling: UXI design system + blocks.
  • Content & configuration: JSON/MDX documents and minimal config.
  • Data & business logic: BFF layers, Odoo, ABS, IoT, and other backend services.
  • Application shell & routing: Next.js app code that wires content + UXI + BFF together.

3. Layered Architecture

OVES UXI is organized into four strict layers.

3.1 Layer 0 – Theme and Design Tokens

Responsibility: Define the visual language of OVES.

  • Implemented in:
  • Tailwind configuration (colors, fonts, spacing, etc.)
  • Global CSS files (e.g. globals.css, additional-styles/theme.css)
  • Provides:
  • Color tokens such as ovesBg, ovesAccent, ovesAccentSoft, ovesText, ovesMuted
  • Typography scale (heading sizes, body text, captions)
  • Shared spacing, borders, radii, shadows, gradients
  • Rules:
  • Only design-authorized changes allowed.
  • No new one-off colors or arbitrary inline styles in application code.

3.2 Layer 1 – UXI Library (Primitives, Blocks, Layout)

Responsibility: Provide the only approved building blocks for OVES web UIs.

  • Implemented under a dedicated namespace (conceptually src/uxi/):
  • Primitives: layout containers, section wrappers, typography components (if needed)
  • Blocks: reusable sections such as:
    • Hero
    • FeatureGrid
    • StatsStrip
    • SplitSection
    • CTASection
    • Future dashboard blocks (KPI tiles, charts, tables, timelines)
    • Future transactional blocks (forms, lists, detail views)
  • Layout: AppShell, footers, headers, navigation that are common across OVES sites.
  • Renderer: PageRenderer and BlockRegistry to map JSON-defined blocks to React components.
  • Rules:
  • Only the UXI library layer may use Tailwind classes directly.
  • Blocks use only Layer 0 tokens – never arbitrary colors or ad-hoc styles.
  • Any new visual pattern is introduced here, reviewed, and then consumed via JSON in apps.

3.3 Layer 2 – Content Schemas (JSON / MDX)

Responsibility: Describe what appears on each page and how it is structured, without styling.

  • Implemented as JSON/MDX documents such as content/pages/home.json.
  • Typical schema:
  • Page-level properties (e.g. layout: "landing")
  • A list of blocks, each with:
    • type: e.g. "hero", "features", "cta", "statsStrip"
    • props: data and configuration for that block (titles, copy, IDs, links, media references).
  • Rules:
  • JSON must fully determine the block sequence and behavior.
  • No style decisions in content (no CSS classes, only semantics and configuration flags).
  • Content authors and product teams can change site behavior by editing JSON/MDX, without touching code.

3.4 Layer 3 – Next.js Applications

Responsibility: Wire UXI to real data and routes.

  • Implemented as Next.js apps (e.g. uxi-landing) that:
  • Read JSON/MDX content
  • Call UXI PageRenderer with the content and block registry
  • Integrate with BFFs and backend services to load dynamic data
  • Provide routing, meta tags, and minimal app-level logic
  • Rules:
  • No custom styling – Next.js app code uses UXI blocks only.
  • All visual behavior comes from Layer 1 + Layer 0.
  • All data access flows through BFFs or backend abstractions, not directly from UI to Odoo/ABS/etc.

4. Vendor Resources and Their Role

(…remaining sections about vendor templates, Cloudinary/media assets, use cases, governance, and relation to @oves/uxi-engine can be kept exactly as in uxi-architecture.md; they are already well structured for this page.)