Integration ready by design
New external systems are added as adapters behind existing platform interfaces, never as a redesign of the modules that use them.
Principles
Four integration commitments
Applied to every external system the platform connects with, today and in future markets.
Secure API exchange only
Encrypted, authenticated APIs with least-privilege scopes, server-side credentials and validated payloads in both directions.
Providers remain replaceable
No provider vocabulary enters the domain model, so payment, mapping or intelligence providers can be exchanged with minimal operational impact.
Failures stay contained
Each dependency is time-bounded and monitored; an unavailable service degrades one panel while the platform keeps operating.
Integration register
Every external domain, its contract and its fallback
Each domain records the providers it is engineered for, the interface contract, the data exchanged and what happens when the service is unavailable.
Article 7
Artificial intelligence services
Advisory, diagnosis and knowledge assistance across the platform, grounded in the nakhelland knowledge base.
Supported providers
- Managed AI gateway (multi-model)
- Alternate model providers behind the same interface
Interface contract
Server-side request/response and streaming interface with a model identifier parameter.
Data exchanged
Question text, selected consultation mode and optional attached imagery. No account credentials.
Failure isolation
The assistant renders inside a module boundary; an unavailable model returns a clear message while the rest of the page continues to work.
Article 2 & 13
Identity and authentication
One enterprise identity per person, with federated sign-in where the person already has a trusted account.
Supported providers
- Platform email identity
- Google federated sign-in
Interface contract
OAuth 2.0 authorisation code flow returning a session validated on every request.
Data exchanged
Name, email address and avatar reference. Roles are never accepted from an external provider.
Failure isolation
A provider outage disables that sign-in method only; other methods and all public content remain available.
Article 6
Communication services
Enterprise correspondence, operational alerts and direct contact with advisory teams.
Supported providers
- WhatsApp Business
- Transactional email
- SMS
- Push notifications
Interface contract
Outbound message API with template identifier, recipient reference and structured variables.
Data exchanged
Recipient contact reference and template variables. Message bodies avoid sensitive business detail.
Failure isolation
Messaging is asynchronous. A failed send is retried and recorded; no page or workflow blocks on delivery.
Article 11
Document services
Formal enterprise documents: proposals, reports, certificates and signed agreements.
Supported providers
- PDF generation
- Electronic document exchange
- Digital certificates
- Electronic signature
Interface contract
Document request describing template, data payload and required signatories; returns a stored document reference.
Data exchanged
Document data payload and signatory identity references, retained under the platform retention policy.
Failure isolation
Generation runs out of band; the requesting page continues and the document appears when it is ready.
Article 4
Payment platforms
Commercial settlement for services, supply and investment participation across regions.
Supported providers
- Credit cards
- Bank transfer
- Digital wallets
- Local gateways
- International providers
Interface contract
Hosted checkout with a server-verified webhook confirming settlement; the platform never handles raw card data.
Data exchanged
Order reference, amount, currency and payer reference. Card credentials remain with the provider.
Failure isolation
A gateway outage blocks new settlement attempts only; catalogues, accounts and advisory services continue.
Article 5
Map, GIS and satellite services
Farm mapping, plot geometry, site planning and remote condition monitoring.
Supported providers
- Google Maps
- OpenStreetMap
- GIS platforms
- Satellite imagery
- Farm mapping systems
Interface contract
Geospatial query interface returning standard coordinate geometry; the platform stores geometry, not tiles.
Data exchanged
Plot coordinates and area geometry. Owner identity is never sent to a mapping provider.
Failure isolation
Maps load client-side behind a boundary; an unavailable tile service degrades to tabular plot data.
Article 12
Media, storage and delivery
Imagery, video and document delivery at international performance levels.
Supported providers
- Cloud object storage
- Content delivery network
- Image libraries
- Video platforms
Interface contract
Signed upload and time-limited read URLs; the platform stores references rather than binary content.
Data exchanged
Media binaries and their metadata. Access to private media always requires a signed, expiring URL.
Failure isolation
Delivery failures degrade to placeholder media; text content and functionality are unaffected.
Article 8
ERP integration
Finance, inventory, procurement, operations and human resources continuity with corporate systems.
Supported providers
- Enterprise resource planning platforms
Interface contract
Scheduled and event-driven synchronisation on permanent record identifiers, with reconciliation reporting.
Data exchanged
Master records, transactions and reference data mapped to the enterprise data dictionary.
Failure isolation
Synchronisation is queued. A paused connection delays reconciliation without interrupting daily operation.
Article 9
CRM integration
A consistent customer relationship record across advisory, commercial and support activity.
Supported providers
- Customer relationship management platforms
Interface contract
Bidirectional contact and opportunity synchronisation keyed on the platform's permanent identifier.
Data exchanged
Contact details, consent state and engagement history, exchanged only with a lawful basis.
Failure isolation
Customer records remain authoritative in the platform; a CRM outage delays synchronisation only.
Article 10
Government and regulatory services
Licensing, registration, compliance reporting and official verification where legally permitted.
Supported providers
- National and regional government platforms
Interface contract
Authenticated submission and verification interfaces published by the responsible authority.
Data exchanged
Only the fields the authority requires, with explicit legal basis and a permanent audit record.
Failure isolation
Submissions are queued and receipted; an unavailable authority service never blocks platform operation.
Integration standard
Seven steps before any external system is enabled
No integration is activated until every step is documented and reviewed. The same standard applies to a payment gateway and to a mapping service.
1 · Business case and data map
Record why the integration exists, which entities it touches, and exactly which fields leave or enter the platform.
2 · Interface contract
Define the request and response shapes, the provider version in use, and the platform-side interface the adapter satisfies.
3 · Credential and scope review
Store credentials as server-side secrets, request least-privilege scopes only, and document the rotation owner.
4 · Validation in both directions
Schema-validate outbound payloads and inbound responses or webhooks, and verify webhook signatures before any processing.
5 · Isolation and degradation
Time-bound every call, wrap the consuming surface in a module boundary, and define the degraded experience in writing.
6 · Observability
Emit status, latency and a correlation identifier for each call, and add the dependency to health monitoring.
7 · Exit plan
State the replacement provider or manual fallback and confirm no provider vocabulary has entered the domain model.
Governing articles
How each integration article is practised
Each principle states the enterprise requirement and the concrete engineering practice that satisfies it.
Article 1
Open integration
The platform remains integration-ready; new external systems never force an architectural redesign.
Every external service is reached through an adapter behind a platform interface, so adding a provider adds an adapter rather than changing the modules that consume it.
Article 2
API first
Enterprise integrations use secure APIs whenever possible.
Server-side HTTPS calls with authenticated credentials, validated payloads and typed responses. Screen scraping, manual file exchange and shared logins are not accepted integration methods.
Article 3
Standardised integration
External integrations follow one documented enterprise standard.
Each integration completes the seven-step contract below before it is enabled, and is recorded in this register with its provider, data exchanged and isolation behaviour.
Article 13 & 21
Secure and compliant by default
Every external integration complies with enterprise security, privacy and legal policy.
Credentials are stored as server-side secrets and never reach the browser, transport is encrypted, least-privilege scopes are requested, and personal data leaves the platform only with a lawful basis.
Article 14
Failure isolation
Failure of one external service does not interrupt the platform.
Calls are time-bounded and wrapped in module boundaries; a failing provider degrades one panel to a recoverable state while navigation, content and every other module continue.
Article 15
Continuous monitoring
Enterprise integrations are monitored continuously.
Each dependency layer is probed by the public health endpoint, and every outbound call records status, latency and correlation identifiers without recording payload contents.
Article 16
External version management
External API versions are managed to minimise business disruption.
The provider version in use is pinned and recorded; upgrades are validated in preview against the same contract before production, and deprecation notices are tracked per integration.
Article 18
Consistent, auditable exchange
Data exchanged with external systems stays consistent, validated, auditable and secure.
Payloads are schema-validated in both directions, records keep permanent identifiers across systems, and every exchange writes an audit event with actor, timestamp and outcome.
Article 19 & 7
Provider independence
External providers are replaceable with minimal operational impact; vendor lock-in is minimised.
No provider vocabulary enters the domain model. Adapters translate to platform contracts, so a payment, map or intelligence provider can be exchanged without touching business logic.
Article 17 & 20
Global scalability
Integration architecture supports enterprise expansion and international operations.
Region, language and currency are integration parameters rather than assumptions, so a new market adds configuration and a regional provider instead of a parallel system.
Provider independence
Replaceable providers, permanent enterprise records
Vendor lock-in is treated as an operational risk. These rules keep the platform, not the provider, in control of enterprise data.
- Domain models use platform vocabulary; provider identifiers are stored as external references, never as primary keys.
- Each integration domain declares at least one alternative provider or documented manual fallback before enablement.
- Adapters are the only code allowed to know a provider's request shape, so replacement is contained to one module.
- Provider API versions are pinned and recorded, and upgrades are validated in preview against the same contract.
- No provider stores the authoritative copy of an enterprise record; the platform remains the single source of truth.
Questions
Integration questions answered
Status meaning, credential handling, outage behaviour, vendor independence and personal data.
Next step
Planning an integration with nakhelland
Share the system you need connected — payments, ERP, CRM, mapping or a government platform — and our engineering team will return the interface contract, data map and isolation plan.
محتوى ذو صلة
روابط ذات صلة داخل المنظومة
وحدات وأدلة ونقاط دخول مرتبطة داخل هيكل منصة نخيلاند.
ArchitectureArchitecture qualityThe module registry and isolation model every integration plugs into.Security & TrustSecurity frameworkCredential handling, encryption and audit requirements applied to external exchange.DataEnterprise data modelThe identifiers and validation rules that keep exchanged data consistent and auditable.