The Grand Project — Architecture Summary
This file is a concise implementation map. `GRAND_PROJECT_GLOBAL_UI_SPEC.md` is the authoritative UI/layout/theme and frontend architecture reference for all Core and plugin work.
Future substantial work in layouts, CSS, components, website rendering, portal rendering, ecommerce/store frontend, themes, navigation, or branding must read this specification before implementation.
Layers
```text
Identity
└── Central Authentication / SSO
Framework
├── Common Application Framework
└── Administration Portal
Core System Services
├── Update Server
├── Backup / Restore Server
├── Storage Server
└── Analytics Server
Plugin Modules
├── Asset Registry
├── Suppliers
├── Products
├── ServiceVault
│ ├── Customer Portal
│ └── Technician Portal
├── OpsRoom
├── Partner Portal
├── Supplier Portal
├── Business Intelligence & Reporting
├── Website Builder
├── E-commerce
├── Payments & Billing
├── Invoice Generation
├── Lead Pipeline
├── Project Tendering
├── Inventory Tracking
├── Order Processing
└── Developer Platform
```
Core rule
Core provides platform capability. Plugin Modules provide business functionality.
ServiceVault and Asset Registry follow a strict ownership split: Asset Registry owns physical identity and QR authority, while ServiceVault owns servicing, technician workflow, reports, and customer-visible service history. ServiceVault may discover Asset Registry through plugin capabilities, but it must remain bootable in a degraded mode when that integration is absent or disabled.
The technician workflow now runs QR resolution or authorised location lookup, commissioning, service-record capture, review, completion, and customer report generation through the same ServiceVault/Asset Registry boundary.
Installation hierarchy
```text
Installation Type
├── Authentication Server
├── Update Server
├── File Server
└── General Installation
└── Application Profile
├── ServiceVault
├── Commerce Website
└── Custom
```
Installation Type is the top-level architectural role. General-only application profiles are presets layered underneath that choice and still defer to manifest dependency resolution.
Central service split
```text
Central service server roles
├── authentication-server
├── update-server
└── storage-server
Central service client roles
├── authentication-client
├── update-client
└── storage-client
```
General installations must use client roles for shared central services. Dedicated Auth, Update, and File Server deployments expose the corresponding server role and must not automatically enable unrelated business Plugin Modules.
Request path
```text
Request
→ Bootstrap
→ Authentication
→ User/Company Context
→ Routing
→ Permission/Policy
→ Plugin/Framework Service
→ Response
→ Audit
```
Cross-plugin interaction
Prefer:
```text
Framework service/capability
API
Event
Queue
Workflow
```
Never:
```text
direct SQL into another plugin
direct include of another plugin's internals
```
Data rule
One authoritative owner per record. Other modules reference, cache derived values, or store historical snapshots.
Update rule
No live change without a pre-created restore path.
UI, layout and plugin integration notes
- Core owns the authenticated shell, global page framework, typography, breakpoints, form/table/button patterns, and tokenized styling.
- Plugins render their content inside the Core shell through `adminNavigation()` registration rather than replacing global chrome.
- Public contexts (website/portal/store) share a context-aware theme system through registered theme packages and `theme_settings` storage.
- Plugin themes and branding settings are configuration-driven and stored separately from theme package files.
- Theme and layout assets should stay scoped; plugin-level styling should avoid global selectors and should not alter core shell primitives.