Modular by construction
Each capability is an independent module that communicates only through interfaces declared in the registry below.
Principles
Four architectural commitments
Applied to every module, service, interface and future capability in the ecosystem.
Scalable without redesign
Growth adds modules and tables rather than widening existing ones, so a decade of expansion does not require a rebuild.
Faults stay contained
Every significant panel renders inside an isolation boundary; one failing dependency degrades one section, never the platform.
Observable and measurable
Health checks, structured logs, workflow events and activity history make behaviour visible before users are affected.
Diagnostics
Availability is measured, not assumed
A public health endpoint reports the reachability of each layer. It exposes service status only — never business or personal data.
Live service diagnostics
Contacting platform services…
Reading service health
Module registry
Every capability, its interfaces and its dependencies
The registry is the documented contract between modules. A module may depend only on what is listed here, and every dependency is deliberate and one-directional.
Experience layer
Experience Shell
Delivers the unified public experience: navigation, page shell, breadcrumbs, related content, footer and platform widgets.
Operationalv1.4
Declared interfaces
- PageShell / Section · Library — Shared layout contract used by every page.
- Breadcrumbs / RelatedLinks · Library — Location and internal-linking contract.
- Public routes · UI Route — Home, modules, sustainability, contact and governance pages.
Dependencies
Design System · Platform Services
Failure isolation
Chrome renders independently of page data; a failed section degrades to an inline error state.
Domain layer
Knowledge & Content
Structured agricultural and enterprise knowledge with governed article structure, FAQs and calls to action.
Operationalv1.1
Declared interfaces
- knowledgeArticles · Data Contract — Typed article catalogue with sections and FAQs.
- /knowledge, /knowledge/$slug · UI Route — Hub and article routes.
Dependencies
Experience Shell · Search & Discoverability
Failure isolation
Content is statically typed and served with the route; unavailable articles resolve to a not-found state.
Digital Identity
One enterprise identity per person: authentication, profile, account types, preferences, privacy, favorites and activity.
Operationalv1.0
Declared interfaces
- useSession / useProfile / useRoles · Library — Identity read contract for any module.
- has_role(user, role) · Data Contract — Authoritative role check used by access rules.
- /auth, /account · UI Route — Access and personal dashboard routes.
Dependencies
Data Platform · Experience Shell
Failure isolation
Public routes never depend on a session; identity failure limits access, it does not break browsing.
Workflow & Business Process
Documented processes: approval states, responsibilities, service levels, generated tasks, audit history and indicators.
Operationalv1.0
Declared interfaces
- workflowCatalogue · Data Contract — External configuration of every business process.
- useWorkflowRequests / useSubmitWorkflowRequest · Library — Process read and write contract.
- /workflows, /workflow-console · UI Route — Documentation and member console.
Dependencies
Digital Identity · Data Platform
Failure isolation
Console panels load independently; a failing task list leaves requests and history readable.
Innovation & Expansion
Governs how new technologies, markets, partners and business models are evaluated, piloted and adopted without reconstructing the platform.
Foundationv1.0
Declared interfaces
- @/content/innovation · Data Contract — Principles, expansion stages, technology horizons, partners, pilot stages and vision horizons.
- /innovation · UI Route — Public register of innovation governance and expansion sequence.
Dependencies
Experience Shell · Knowledge & Content
Failure isolation
Registry is static content; a pilot capability fails inside its own module boundary without affecting core surfaces.
Intelligence layer
Enterprise Intelligence
Assistant modes for agronomy, diagnosis, investment, design and knowledge navigation, grounded in the knowledge base.
Operationalv1.0
Declared interfaces
- /api/chat · HTTP Endpoint — Streaming assistant contract.
- assistantModes · Data Contract — External configuration of specialised modes.
- /ai · UI Route — Assistant hub, available from every page.
Dependencies
Knowledge & Content · Platform Services
Failure isolation
The assistant is an optional overlay; if the model is unavailable the platform is unaffected.
Platform layer
Design System
Centralized design tokens, typography, buttons, cards, form fields and standardized loading, empty and error states.
Foundationv1.2
Declared interfaces
- Design tokens · Data Contract — Colour, spacing, motion and shadow variables.
- @/components/enterprise · Library — Approved component primitives and states.
- /design-system · UI Route — Living documentation of the component library.
Dependencies
None — this module is a foundation layer.
Failure isolation
Purely presentational; no runtime dependency can fail it.
Search & Discoverability
Enterprise search index, filters, structured data, sitemaps and canonical metadata for human and AI search.
Operationalv1.1
Declared interfaces
- searchIndex / searchPlatform · Library — Index contract and ranking function.
- /search, /sitemap · UI Route — Search interface and human site map.
- /sitemap.xml and index · HTTP Endpoint — Machine-readable discovery contract.
Dependencies
Knowledge & Content
Failure isolation
Search runs in the browser over a local index; it stays usable if backend services are degraded.
Platform Services
Cross-cutting capability every page inherits: preferences, accessibility tools, contact shortcuts, save, share and print.
Operationalv1.1
Declared interfaces
- platform-preferences · Library — Language, currency and accessibility preference contract.
- PlatformWidgets · Library — Global widget mount point.
- /api/public/health · HTTP Endpoint — Diagnostics and availability contract.
Dependencies
None — this module is a foundation layer.
Failure isolation
Preferences degrade to documented defaults when storage is unavailable.
Data layer
Data Platform
Governed storage: authoritative entities, permanent identifiers, audit columns, soft delete and row-level access rules.
Foundationv1.2
Declared interfaces
- Data dictionary · Data Contract — Documented entities, relationships and lifecycle.
- Row level access rules · Data Contract — Per-record authorization enforced in the database.
- /data-architecture · UI Route — Published data documentation.
Dependencies
None — this module is a foundation layer.
Failure isolation
Access rules fail closed: a fault denies data rather than exposing it.
Quality attributes
How each architectural article is practised
Each attribute states the requirement and the concrete engineering practice that satisfies it.
Article 1
Enterprise quality first
Quality takes priority over speed of delivery.
Work is considered complete only when it is documented, accessible, secured and consistent with the design system — not when it first renders.
Article 2
Scalability
The platform expands without a complete redesign.
New capability is added as a new module and new tables, never by widening an existing module beyond its purpose.
Article 3
Modularity
Each capability is an independent module with declared interfaces.
Modules communicate through documented routes, server functions and data contracts listed in the registry below.
Article 4
Maintainability
The architecture stays easy to maintain, modify and extend.
One shared shell, one token set, one component library and one data model keep a change local instead of platform-wide.
Article 5
Reusability
Logic, components and utilities are reused wherever possible.
Shared primitives live in the enterprise component library and shared logic in typed libraries consumed by every module.
Article 6
Performance
Performance is a permanent design objective.
Server rendering, route-level code splitting, cached queries and lazy media keep first render fast as content grows.
Articles 7 & 9
Reliability & availability
Critical services remain stable and available under continuous use.
Managed infrastructure, stateless request handling and a public health endpoint make degradation visible before users report it.
Article 8
Fault tolerance
A failure in one module never takes down the platform.
Every module section renders inside an isolation boundary with a recoverable error state; a failed panel does not blank the page.
Article 10
Testability
Every feature is testable, including automatically.
Business rules sit in pure functions and typed catalogues, separated from presentation so they can be exercised without a browser.
Article 11
Observability
Monitoring, logging, metrics, diagnostics and health checks are supported.
Workflow events, user activity history, structured server logs and the health endpoint provide the diagnostic surface.
Article 12
External configuration
Business values are configuration, not code.
Catalogues, statuses, service levels and reference values are declared in registries; secrets are injected at runtime, never committed.
Articles 13 & 14
Versioning & compatibility
Services evolve under version control without disrupting what exists.
Contracts are extended additively, published paths are preserved with redirects, and breaking change requires a new version.
Articles 15 & 16
Documentation & dependencies
Architecture and its dependencies stay documented continuously.
This register is updated in the same change as the code it describes; dependencies are declared per module and kept acyclic.
Article 17
Resource efficiency
Memory, storage, processing and bandwidth are used responsibly.
Queries select only required columns, assets are compressed and generated content is cached rather than recomputed.
Articles 18–21
Continuous improvement & AI readiness
The architecture evolves and stays ready for AI in every module.
Structured, well-labelled data and a shared assistant interface allow intelligence to be added to a module without restructuring it.
Configuration & versioning
Business values stay outside the code
Hard-coded business values are treated as defects. Configuration is declared, reviewable and versioned alongside the capability it governs.
| Scope | Held in |
|---|---|
| Business cataloguesWorkflow catalogue, assistant modes, data dictionary, search index, this architecture register. | Typed registries under the content layer |
| Presentation valuesPalette, typography scale, spacing rhythm, elevation and motion durations. | Design tokens in the global stylesheet |
| Reference dataAccount types, roles, statuses and lookup values shared across modules. | Database reference tables |
| Secrets and credentialsService keys and model credentials, read on the server at call time and never committed. | Runtime environment injection |
Versioning & backward compatibility
- Interfaces are extended additively: new optional fields, never repurposed existing ones.
- A breaking change to a published contract requires a new version rather than an in-place edit.
- Published URLs are preserved; a moved page keeps its old path working through a permanent redirect.
- Database change is delivered as a forward migration with documented intent and reversible data handling.
- Every module in the registry carries a version so dependants can reason about compatibility.
Decision record
Architecture decisions on the record
Significant decisions are documented with their rationale and consequence, so future teams inherit the reasoning and not only the result.
ADR-001
Server-rendered application shell
- Decision
- The platform is server rendered with route-level code splitting.
- Rationale
- Discoverability, first-render performance and accessibility all improve when content exists in the initial response.
- Consequence
- Browser-only capability must be isolated behind explicit client boundaries.
ADR-002
Authorization enforced in the database
- Decision
- Access rules live with the data, not in the interface layer.
- Rationale
- Every access path — interface, service or integration — is then governed by the same rule.
- Consequence
- New tables are unusable until their access rules and grants are declared, which is intentional.
ADR-003
Configuration as typed registries
- Decision
- Business catalogues are declared as typed registries rather than embedded in pages.
- Rationale
- Business change becomes a configuration edit, is reviewable, and can be tested without a browser.
- Consequence
- Registries must be maintained in the same change as the capability they describe.
ADR-004
Module-level failure isolation
- Decision
- Each significant panel renders inside an isolation boundary with a recoverable error state.
- Rationale
- One failing dependency should degrade one panel, never the whole platform.
- Consequence
- Modules must return usable partial results instead of throwing to the page root.
ADR-005
One identity, roles held separately
- Decision
- A person has one enterprise identity; roles are stored in a dedicated table and checked by a governed function.
- Rationale
- Separating roles from profiles removes the privilege-escalation path and keeps permissions auditable.
- Consequence
- Elevated roles are assigned by administration only and can never be self-selected.
Questions
Architecture questions answered
Extension, failure behaviour, configuration, compatibility and AI readiness.
Architecture review
Reviewing nakhelland as a long-term platform decision
Technical, procurement and governance teams can request the detailed architecture briefing, integration contracts and module roadmap.
محتوى ذو صلة
روابط ذات صلة داخل المنظومة
وحدات وأدلة ونقاط دخول مرتبطة داخل هيكل منصة نخيلاند.
DataEnterprise data modelThe governed entities, identifiers and lifecycle the architecture is built on.Security & TrustSecurity frameworkZero trust, least privilege, encryption and audit logging across every module.GovernanceBusiness workflowsHow documented processes run on top of these architectural foundations.