The Grand Project — Master Specification
**Status:** Authoritative project specification
**Purpose:** Source of truth for implementation by Codex and human developers
**Rule:** If any summary, secondary document, code comment, or older prompt conflicts with this file, this file wins.
**Implementation note (August 12, 2026):** The current first operational deployment path is `Central Authentication -> Common Application Framework -> Administration -> Website Builder -> public site rendering`. Deferred business Plugin Modules may retain valid contracts and scaffolds without yet being functionally complete; implementation status must distinguish real runtime behavior from scaffold completion.
---
1. Vision
The Grand Project is a modular web application platform intended to run multiple applications across different domains and subdomains while sharing common platform services, identity, infrastructure, security standards, installation/update mechanisms, and reusable framework capabilities.
The platform must support independently installed and versioned Plugin Modules without forcing each application to reinvent authentication, permissions, storage, PDF generation, notifications, logging, updates, recovery, APIs, background jobs, or AI integration.
Core principle:
> **Core provides platform capability. Plugin Modules provide business functionality. Dependencies are explicit. Updates are reversible.**
---
2. Canonical Project Layout
Canonical Windows project root:
`C:\Users\Administrator\Desktop\Storage\Projects\The Grand Project`
Logical structure:
```text
The Grand Project/
├── GRAND-PROJECT-SPECIFICATION.md
├── ARCHITECTURE.md
├── DEPENDENCIES.md
├── SECURITY.md
├── CODEX-HANDOVER-PROMPT.md
├── todo.md
├── updates.md
├── decisions.md
│
├── Core Platform/
│ ├── Authentication/
│ ├── Common Application Framework/
│ └── Administration/
│
├── Core System Services/
│ ├── Update Server/
│ ├── Backup Restore Server/
│ ├── Storage Server/
│ └── Analytics Server/
│
└── Plugin Modules/
├── Asset Registry/
├── Suppliers/
├── Products/
├── ServiceVault/
├── 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/
```
All installable business applications belong under **Plugin Modules**. Do not introduce alternate categories such as “foundational first-party plugins” or “business application plugins”.
---
3. Core Platform
3.1 Central Authentication Service
A central identity provider used by all Grand Project applications.
Responsibilities:
- Email/password authentication
- Google login
- Apple login
- MFA
- Email verification
- Password reset
- User suspension/reactivation
- Login attempt logging
- Session/device history
- Global logout
- Cross-domain SSO
- OAuth 2.0 / OpenID Connect compatible flows
- User/service/agent identities
- Stable non-sequential public user identifiers
- Service credential support
- Revocation and credential rotation
Plugin Modules must never store passwords or implement competing authentication systems.
3.2 Common Application Framework
The shared runtime used by all Grand Project installations and Plugin Modules.
It provides:
- Bootstrap/runtime
- Routing
- Templating and shared UI
- Request context
- Authentication integration
- Company/tenant context
- Roles and permissions
- Policies
- Database abstraction
- Migrations
- Plugin discovery/loader
- Dependency resolver
- Plugin registry
- Configuration
- Secrets
- Storage abstraction
- File/document service integration
- PDF/document generation
- Notifications/email
- Logging/audit
- Events
- Queues/background jobs
- Scheduler
- Workflow/saga support
- APIs/service interfaces
- AI-agent integration
- Health checks
- Diagnostics
- Installer
- Updater
- Backup/rollback hooks
- Recovery support
- Security controls
3.3 Central Administration Portal
The platform control plane.
Manages:
- Installation health
- Users
- Companies/organisations
- Relationships
- Roles
- Permissions
- Plugin Modules
- Plugin dependencies
- Core System Services
- Updates
- Backup/restore
- Storage
- Queues/jobs
- Scheduler
- Integrations
- Service/API credentials
- AI agents
- Notifications
- Logs
- Audit
- Health
- Diagnostics
- Configuration
- Security controls
The Administration Portal manages the platform. It is not a general-purpose editor for business records owned by Plugin Modules.
3.4 Company and Relationship Service
Central organisation/relationship model.
Supports:
- Companies
- Trading names
- Customers
- Suppliers
- Partners
- Employees
- Contractors
- Technicians
- Third-party technicians
- Contacts
- Sites/properties
- Departments
- Relationship types
- Historical relationship records
- Start/end dates
- Status
- Ownership transfer history where relevant
One user account may simultaneously be any permitted combination of:
- Customer
- Supplier
- Partner
- Employee
- Technician
- Administrator
- Contractor
- Other future relationship types
Do not create duplicate accounts merely because a person has multiple roles.
3.5 Shared File and Document Service
Common file identity, metadata, secure access, versioning, storage-provider abstraction and retention.
Applications store file IDs, not hardcoded filesystem paths.
3.6 Notification and Communications Service
Common in-app notifications, email, system notices and future SMS/push channels.
3.7 PDF and Report Engine
Shared HTML-to-PDF/document generation, templates, versioning and archival snapshots.
Chrome/Chromium headless is preferred where practical.
3.8 Audit and Logging Service
Central structured operational logging plus append-only audit records.
3.9 Background Jobs and Scheduler
Shared queue, worker, retry, dead-letter, scheduled-task and long-running workflow infrastructure.
3.10 API and Integration Service
Versioned APIs, service-to-service credentials, scopes, webhooks, rate limiting, integration adapters, request tracing and API conventions.
3.11 Application and Plugin Registry
Tracks installed modules, versions, manifests, dependencies, capabilities, health, configuration state and lifecycle status.
3.12 Monitoring, Backup and Recovery Integration
Health checks, backup orchestration, restore points, update safeguards and emergency recovery interfaces.
3.13 AI Agent Integration Service
Secure standard gateway for AI agents.
Supports:
- Agent registration
- Agent identities
- Scoped credentials
- Allowed tools/actions
- Company/application context
- Approved file/search access
- Read/write scopes
- Human approval gates
- Usage/cost tracking
- Rate/spend limits
- Prompt/agent versioning
- Scheduled/background jobs
- Multiple providers
- Local models
- Audit
- Revocation
- Prompt-injection protections
- Sensitive-data controls
AI agents must not receive unrestricted database access.
---
4. Core System Services
These are separately deployed platform service plugins under `Core System Services/`.
4.1 Update Server
Responsibilities:
- Publish signed framework releases
- Publish signed Plugin Module releases
- Version metadata
- Compatibility metadata
- Release channels
- Checksums
- Digital signatures
- Release notes
- Package retrieval
Supported channels:
- stable
- beta
- development
The Update Server never directly modifies an installation. Installations pull, verify and apply updates locally.
4.2 Backup / Restore Server
Responsibilities:
- Store or coordinate encrypted backup sets
- Store backup manifests
- Restore-point metadata
- Remote backup retention
- Verification metadata
- Recovery support
The local installation remains capable of local backup/restore even if the remote server is unavailable.
4.3 Storage Server
Shared storage/object service.
Supports:
- Secure upload/download
- Private/public files
- Metadata
- File versions
- Retention
- Storage policies
- Secure temporary URLs
- Provider abstraction
- Future cloud storage backends
4.4 Analytics Server
Receives approved:
- Operational telemetry
- Health metrics
- Performance data
- Usage data
- Authorised analytical events
Business analytics must respect company boundaries and configured privacy controls. Analytics is not a secret copy of every business database.
---
5. Plugin Modules
Current Plugin Modules:
1. Asset Registry
2. Suppliers
3. Products
4. ServiceVault
5. OpsRoom
6. Partner Portal
7. Supplier Portal
8. Business Intelligence & Reporting
9. Website Builder
10. E-commerce
11. Payments & Billing
12. Invoice Generation
13. Lead Pipeline
14. Project Tendering
15. Inventory Tracking
16. Order Processing
17. Developer Platform
5.1 Asset Registry
Authoritative source for:
- Assets
- Asset types
- Asset classes/plugins
- Specifications
- Properties
- Locations
- Parent/child asset relationships
- Ownership/responsibility relationships
- Installation history
- Service/lifecycle events
- Maintenance definitions
- Maintenance schedules
- Common fault definitions
- Warranties
- Manuals
- Documents
- QR identifiers
- Equipment knowledge
Asset Registry is an ordinary Plugin Module in the Plugin Modules folder, not a special “core first-party application” category.
Asset-class plugin architecture must support initial classes:
- Generic Equipment
- Pool
- Spa
- Pump
- Filter
- Salt Chlorinator
- Chemical Dosing System
- Heat Pump
- HVAC
- Refrigeration
The Pool asset plugin is the first complete specialised reference implementation.
5.2 Suppliers
Authoritative supplier records and supplier relationships.
Supports:
- Supplier records
- Supplier contacts
- Terms
- Lead times
- Catalogues
- Preferred-supplier status
- Purchasing information
- Supplier/product relationships
5.3 Products
Authoritative product catalogue.
Supports:
- Products
- SKUs
- Brands
- Models
- Variants
- Specifications
- Pricing references
- Documents
- Supplier relationships
- Links to inventory/e-commerce/sales/invoicing
5.4 ServiceVault
Owns:
- Service requests
- Work orders
- Technician assignments
- Site visits
- Fault/repair workflows
- Service reports
- Dynamic report templates
- Water test reports
- Water dosing reports
- Maintenance completion data
- Report delivery
- Customer service communications
ServiceVault contains:
- Customer Portal
- Technician Portal
- Third-party technician interfaces as appropriate
These are internal ServiceVault modules, not standalone top-level Plugin Modules.
ServiceVault references Asset Registry through declared framework/API services.
5.5 OpsRoom
Internal operations platform.
Includes:
- Projects
- Procedures
- Documents
- Internal workflows
- Business knowledge
- Management tools
**Tendering is not part of OpsRoom.**
5.6 Partner Portal
Partner/distributor/reseller-facing access based on role and relationship.
5.7 Supplier Portal
Supplier-facing interface for authorised:
- Supplier records
- Catalogues
- Products
- Documents
- Purchasing interactions
- Communications
5.8 Business Intelligence & Reporting
Dashboards, KPIs, authorised analytical views, reporting and exports.
Derived analytical data is not authoritative over source plugins.
5.9 Website Builder
Websites, pages, layouts, themes, blocks, menus, forms, media, SEO, publishing, domains.
5.10 E-commerce
Products, variants, categories, carts, checkout, orders, discounts, shipping, tax, returns and refunds.
5.11 Payments & Billing
Supports:
- Stripe
- PayPal
- Future payment providers
- One-off payments
- Deposits
- Payment links
- Partial payments
- Recurring payments
- Subscriptions
- Refunds
- Failed-payment handling
- Reconciliation
- Provider webhooks
- Transaction logs
- Receipts
- Xero API integration
Xero integration may synchronise configured accounting data including contacts, invoices, credit notes, payments, refunds, tax information and payment references.
Payments & Billing does not store raw card details.
5.12 Invoice Generation
Owns:
- Invoices
- Credit notes
- Statements
- Numbering
- Tax calculations
- Invoice PDF output
- Delivery status
- Payment status
- Overdue reminders
5.13 Lead Pipeline
Renamed from Sales Floor.
Owns:
- Leads
- Opportunities
- Enquiries
- Quotes
- Estimates
- Revisions
- Approvals
- Deposits
- Pipeline stages
- Conversion into orders/projects/invoices
It does **not** require Suppliers. Supplier integration is optional.
5.14 Project Tendering
Standalone Plugin Module for tender opportunities and submissions.
Includes:
- Tender register
- Requirements
- Scope breakdown
- Pricing inputs
- Deadlines
- Clarifications
- Site visits
- Compliance documents
- Approvals
- Submission packs
- Tender status
5.15 Inventory Tracking
Owns:
- Stock on hand
- Available stock
- Reserved stock
- Multiple warehouses
- Stores
- Bin locations
- Vehicles
- Technician stock
- Transfers
- Receipts
- Sales allocations
- Returns
- Adjustments
- Serial numbers
- Batch/lot tracking
- Reorder levels
- Stocktakes
- Stock movement history
- Inventory valuation
5.16 Order Processing
Owns order fulfilment workflows:
- Allocation
- Fulfilment
- Picking
- Packing
- Dispatch
- Completion
- Cancellation/recovery states
5.17 Developer Platform
Developer tooling:
- Scaffolding
- Diagnostics
- Migrations
- Test support
- Deployment utilities
- Documentation
- Plugin validation
- Contract testing
---
6. Canonical Plugin Dependency Model
6.1 Required dependencies
- ServiceVault → Asset Registry
- Inventory Tracking → Products
- Order Processing → Inventory Tracking
- Payments & Billing → Invoice Generation
- E-commerce → Products
- E-commerce → Suppliers
- E-commerce → Payments & Billing
- E-commerce → Invoice Generation
- Supplier Portal → Suppliers
6.2 Important optional integrations
- Lead Pipeline ↔ Suppliers
- Lead Pipeline ↔ Products
- Lead Pipeline ↔ Project Tendering
- Lead Pipeline ↔ Invoice Generation
- Lead Pipeline ↔ Order Processing
- E-commerce ↔ Inventory Tracking
- E-commerce ↔ Order Processing
- E-commerce ↔ Website Builder
- ServiceVault ↔ Products
- ServiceVault ↔ Inventory Tracking
- ServiceVault ↔ Invoice Generation
- ServiceVault ↔ Payments & Billing
- Products ↔ Suppliers
- Project Tendering ↔ Lead Pipeline
- Project Tendering ↔ Products
- Project Tendering ↔ Suppliers
- Project Tendering ↔ Invoice Generation
Required dependencies must be kept minimal. Useful but non-essential integrations remain optional.
6.3 Transitive dependencies
The resolver must understand transitive dependencies.
Example:
```text
Order Processing
└── Inventory Tracking
└── Products
```
Order Processing does not need to redundantly declare Products if Inventory Tracking already requires it.
---
7. Plugin Manifest
Every Plugin Module contains an authoritative `plugin.json`.
Minimum canonical shape:
```json
{
"schema_version": 1,
"id": "servicevault",
"name": "ServiceVault",
"package": "grand-project/servicevault",
"version": "1.0.0",
"description": "Service and maintenance management application.",
"framework": {
"minimum_version": "1.0.0",
"maximum_version": null
},
"database": {
"connection": "default",
"table_prefix": "svc_",
"migrations": "database/migrations",
"seeders": "database/seeders"
},
"dependencies": {
"required": [],
"optional": [],
"recommended": [],
"conflicts": []
},
"provides": [],
"permissions": [],
"routes": {
"web": "routes/web.php",
"api": "routes/api.php"
},
"events": {
"publishes": [],
"subscribes": []
},
"jobs": [],
"navigation": "config/navigation.php",
"configuration": "config/plugin.php",
"installation": {
"installer": "install/install.php"
},
"updates": {
"updater": "updates/update.php"
},
"rollback": {
"supported": true
},
"uninstall": {
"data_policy": "retain",
"supports_full_removal": true
},
"health_checks": [],
"enabled_by_default": false
}
```
The manifest may additionally declare:
- exact/min/max dependency versions
- auto-install permission
- capabilities
- API versions
- migration safety metadata
- company availability
- feature flags
- provider requirements
- install/update hooks
No undeclared hard dependency may be introduced at runtime.
---
8. Dependency Resolver
Before installing/updating/enabling/disabling:
1. Read manifests.
2. Build full dependency graph.
3. Resolve transitive dependencies.
4. Detect missing dependencies.
5. Check version compatibility.
6. Check framework compatibility.
7. Check capability providers.
8. Detect conflicts.
9. Detect circular dependencies.
10. Calculate safe order.
11. Calculate reverse dependencies.
12. Determine transaction scope.
13. Back up before changes.
Required dependency rules:
- Must be installed.
- Must be enabled.
- Must meet version requirements.
- Must pass required health checks.
Optional dependencies:
- Absence does not block plugin operation.
- Related features remain disabled/unregistered.
Disabling a dependency is blocked if an enabled plugin requires it.
Circular dependency example:
```text
A → B → C → A
```
must stop with a clear error.
Each installation maintains a dependency lock file recording exact installed versions.
---
9. Plugin Module Physical Package Structure
Standard package:
```text
plugin-module/
├── plugin.json
├── README.md
├── CHANGELOG.md
├── LICENSE
│
├── config/
│ ├── plugin.php
│ ├── navigation.php
│ └── permissions.php
│
├── routes/
│ ├── web.php
│ └── api.php
│
├── src/
│ ├── Plugin.php
│ ├── Controllers/
│ ├── Services/
│ ├── Models/
│ ├── Repositories/
│ ├── Policies/
│ ├── Events/
│ ├── Listeners/
│ ├── Jobs/
│ ├── Notifications/
│ ├── Validators/
│ ├── Integrations/
│ └── Support/
│
├── database/
│ ├── migrations/
│ ├── seeders/
│ └── factories/
│
├── resources/
│ ├── views/
│ ├── templates/
│ ├── css/
│ ├── js/
│ ├── images/
│ └── lang/
│
├── api/
│ ├── schemas/
│ └── documentation/
│
├── install/
│ ├── install.php
│ ├── uninstall.php
│ └── checks.php
│
├── updates/
│ ├── migrations/
│ └── hooks/
│
├── health/
│ └── checks.php
│
├── tests/
│ ├── Unit/
│ ├── Feature/
│ └── Integration/
│
└── storage/
└── .gitkeep
```
Plugin code remains self-contained. Installers must not scatter plugin source files through framework directories.
Code lives in Plugin Modules.
Configuration lives in configuration storage.
Data lives in databases.
Files live in the Storage/File Service.
Identity lives in Authentication.
Dependencies live in the manifest.
---
10. Plugin Lifecycle
10.1 Discovery/boot
```text
Discover package
→ Validate manifest
→ Resolve dependencies
→ Check compatibility
→ Register plugin
→ register()
→ boot()
→ Register routes/permissions/events/jobs/navigation
→ Health checks
→ Active
```
`register()` registers services/bindings.
`boot()` executes after framework and required dependencies are available.
10.2 Plugin states
Suggested states:
- discovered
- installing
- installed
- enabling
- enabled
- disabled
- updating
- failed
- rollback_pending
- incompatible
- uninstalling
Filesystem presence means only “package exists”. Registry state determines whether it is installed and runnable.
10.3 Disable
Before disable:
- Check reverse dependencies.
- Stop accepting new plugin jobs.
- Pause/cancel/drain existing work according to policy.
- Remove routes/navigation/listeners.
- Preserve historical data.
10.4 Uninstall
Default data policy is `retain`.
Supported policies:
- retain
- archive
- delete_with_confirmation
Destructive removal requires explicit confirmation and backup.
---
11. Common Application Framework Internal Structure
```text
Common Application Framework/
├── public/
│ ├── index.php
│ └── assets/
├── bootstrap/
│ ├── app.php
│ ├── autoload.php
│ └── environment.php
├── config/
│ ├── app.php
│ ├── auth.php
│ ├── database.php
│ ├── storage.php
│ ├── services.php
│ ├── plugins.php
│ ├── security.php
│ └── updates.php
├── src/
│ ├── Application/
│ ├── Auth/
│ ├── Authorization/
│ ├── Companies/
│ ├── Config/
│ ├── Database/
│ ├── Events/
│ ├── Files/
│ ├── HTTP/
│ ├── Logging/
│ ├── Notifications/
│ ├── PDF/
│ ├── Plugins/
│ ├── Queue/
│ ├── Routing/
│ ├── Security/
│ ├── Services/
│ ├── Storage/
│ ├── Updates/
│ └── Support/
├── routes/
│ ├── web.php
│ ├── api.php
│ └── system.php
├── resources/
│ ├── views/
│ ├── layouts/
│ ├── components/
│ ├── css/
│ ├── js/
│ └── lang/
├── database/
│ ├── migrations/
│ ├── seeders/
│ └── schema/
├── storage/
│ ├── cache/
│ ├── logs/
│ ├── sessions/
│ ├── temp/
│ └── recovery/
├── installer/
├── updater/
├── recovery/
├── tests/
├── vendor/
├── composer.json
└── framework.json
```
---
12. Request Lifecycle
Normal web request:
```text
HTTP Request
→ public/index.php
→ Bootstrap
→ Environment/config
→ Logging
→ Database
→ Plugin registry
→ Resolve enabled plugins
→ Authentication
→ User context
→ Company/tenant context
→ Routing
→ Permission/policy
→ Controller/plugin handler
→ Business logic
→ Render response
→ Audit important changes
→ Return response
```
Middleware order should normally include:
```text
Request ID
→ Security Headers
→ Maintenance Mode
→ Authentication
→ Company Context
→ Rate Limiting
→ CSRF (web)
→ Permission Check
→ Handler
→ Audit
```
Request types:
- web
- API
- system
Every request has a context object with, as applicable:
- request_id
- correlation_id
- user_id
- service_id
- company_id
- relationship_id
- application_id
- plugin_id
- roles
- permissions
- locale
- timezone
- auth type
---
13. Authentication, Relationships and Authorisation
Security decision order:
```text
Who are you?
→ Are you active?
→ Which organisation are you acting for?
→ What relationship do you have with it?
→ Can you access this application?
→ Do you have the permission?
→ Does that permission cover this record?
→ Is this action allowed in this state?
→ Proceed
```
Roles are collections of permissions.
Business logic must check permissions rather than hardcoded role names.
Permission naming:
`plugin.resource.action`
Examples:
- `asset_registry.assets.read`
- `servicevault.work_orders.assign`
- `inventory.stock.transfer`
- `invoices.invoice.credit`
Scoped permission concepts:
- own
- assigned
- location
- company
- all
Record policies determine access to a specific record.
System administrator elevation/impersonation must be visible and audited.
Suspension can occur at:
- global account
- company relationship
- application/plugin access
---
14. Multi-Company / Tenant Model
Company-private records contain a company identifier.
Framework-level query scoping should automatically enforce active company context.
Plugins must not trust a submitted `company_id` without validating current access.
Visibility classes:
- global
- company
- shared
Examples of global/shared records may include generic manufacturer/model/manual data. Installed assets, private notes and company-specific records remain company-scoped.
---
15. Database and Data Ownership
Each Plugin Module owns its tables.
Example prefixes:
- `ar_` Asset Registry
- `prd_` Products
- `sup_` Suppliers
- `svc_` ServiceVault
- `inv_` Inventory Tracking
- `ord_` Order Processing
- `invx_` Invoice Generation
- `pay_` Payments & Billing
- `lead_` Lead Pipeline
- `ten_` Project Tendering
Exact prefixes must be unique and stable once released.
Rules:
- Plugin may directly query/write only its own tables.
- Cross-plugin access uses services/APIs/capabilities/events.
- Database foreign keys are encouraged within a plugin.
- Avoid database-level foreign keys across plugin boundaries.
- Cross-plugin references use stable public identifiers.
- Important records use internal primary key + public-safe ID.
- Public URLs/APIs must not rely on sequential database IDs.
15.1 Reference + snapshot
Historical records store both live references and snapshots where required.
Examples:
- invoice lines
- orders
- quotes
- service reports
- tenders
- ownership transfers
This preserves historical truth if source records later change.
15.2 Data ownership
One authoritative owner per business record.
Other plugins may:
- reference
- read through services
- cache derived non-authoritative data
- store historical snapshots
- react to events
They do not become co-owners.
---
16. Migrations
All schema changes use migrations.
Plugin migrations modify only that plugin’s own tables.
Migration metadata should track:
- plugin_id
- migration name
- version
- applied time
- checksum
Migration classes:
- safe
- caution
- destructive
Examples:
Safe:
- add nullable column
- add table
- add index
Caution:
- type change
- rename
- backfill
Destructive:
- drop column/table
- destructive historical rewrite
Destructive production migrations require backup and may require explicit approval.
Rollback support must be declared. Where rollback cannot be trusted, restore the pre-update database snapshot.
---
17. Events
Events describe facts that happened.
Good:
- `order.completed`
- `invoice.paid`
- `asset.transferred`
Do not use events as imperative commands.
Standard event envelope includes:
- event_id
- event_type
- event_version
- occurred_at
- source_plugin
- source_record_id
- company_id
- user/service id
- request_id
- correlation_id
- payload
Breaking payload changes require new event versions.
Important asynchronous events should use a durable transactional outbox.
---
18. Queues and Jobs
Shared queue system supports:
- immediate/delayed
- scheduled
- priorities
- retry
- timeout
- idempotency
- company context
- user/service context
- correlation IDs
- dead-letter
- progress
- cancellation
Suggested queues:
- critical
- default
- documents
- integrations
- analytics
- maintenance
- low
Retries distinguish retryable vs permanent failures.
Repeated failures move to dead-letter state.
---
19. Workflows and Cross-Plugin Transactions
Cross-plugin business processes are not giant SQL transactions.
Use saga-style workflows.
Example:
```text
Checkout
→ Create Order
→ Reserve Inventory
→ Create Invoice
→ Create Payment Intent
→ Payment
→ Commit Inventory
→ Fulfil
→ Dispatch
→ Complete
```
Each step declares:
- action
- result
- next step
- failure handling
- compensating action
Workflow state/history must be inspectable in Administration.
Cross-plugin write operations must be idempotent.
---
20. Scheduler
Plugins declare schedules. Framework owns execution.
Examples:
- Xero sync
- maintenance due checks
- update checks
- backup schedules
- analytics
- cleanup
Use locking to prevent duplicate scheduled execution.
The operating system triggers the Grand Project scheduler; plugins do not install separate cron/Task Scheduler entries.
---
21. API Conventions
Versioned routes:
`/api/v1/...`
Standard success shape:
```json
{
"success": true,
"data": {},
"meta": {},
"errors": []
}
```
Standard error shape:
```json
{
"success": false,
"data": null,
"errors": [
{
"code": "permission_denied",
"message": "You do not have permission to perform this action."
}
]
}
```
Support:
- pagination
- filtering
- sorting
- field selection where useful
- request IDs
- correlation IDs
- idempotency keys
- rate limiting
- scopes
- API versioning/deprecation
Internal same-installation calls should prefer framework service/capability interfaces over HTTP.
One capability implementation may have both an internal service interface and remote API adapter.
---
22. Service Identities and API Security
Identity classes include:
- Human identity
- Service identity
- Installation identity
- Agent identity
- External provider identity
Service/API requests require appropriate combinations of:
- valid credential/token
- scope
- application authorisation
- company context
- user/service permission
- record policy where relevant
Credentials must be scoped and rotatable.
---
23. External Integration Adapters
Provider-specific integrations sit behind stable interfaces.
Examples:
Payments & Billing:
- Stripe adapter
- PayPal adapter
- future providers
- Xero adapter
Storage:
- local
- Grand Project Storage Server
- S3-compatible
- Azure Blob
- Google Cloud Storage
- future providers
External API calls should generally use queued jobs and retry policies.
Incoming webhooks:
```text
Receive
→ Verify signature
→ Persist provider event identity
→ Reject duplicate
→ Acknowledge promptly
→ Queue processing
```
---
24. AI Agent Tools
AI agents use approved tools/capabilities rather than raw unrestricted CRUD.
Tool metadata:
- tool name
- description
- input schema
- output schema
- required scopes
- approval requirement
- rate limit
Example allowed tools:
- search_assets
- get_asset_history
- draft_service_report
- prepare_quote
- find_product
- check_stock
- create_invoice_draft
Sensitive actions such as sending invoices, refunds, permission changes or deletions may require explicit human approval.
---
25. Shared Storage and File Model
File record supports:
- file_id/public_id
- company
- owner plugin/record
- original filename
- safe filename
- MIME
- size
- checksum
- provider
- storage key
- visibility
- version
- status
- created/updated metadata
Access resolves:
```text
caller
→ company context
→ owning plugin/record
→ permission/policy
→ storage
```
Knowing a file ID does not grant access.
Uploaded files never become executable merely because they were uploaded.
---
26. PDF / Document Engine
Shared document service accepts:
- template ID
- data
- company context
- output
- storage policy
Support:
- HTML → PDF
- shared/plugin templates
- branding
- headers/footers
- numbering
- tables
- images
- QR/barcodes
- signatures
- attachments
- draft/final
- watermarks
- revisions
- A4/A3
- portrait/landscape
- print CSS
Final historical documents are stored as rendered snapshots with template version/checksum.
---
27. Notifications and Email
Channels:
- in-app
- future SMS
- future push
- webhook
Plugins request notifications; they do not directly implement mail-provider logic.
Email supports:
- SMTP
- transactional providers
- sender identities
- templates
- attachments
- queue/retry
- bounce/failure tracking
- development mail capture
Templates support:
- subject
- HTML
- text
- variables
- branding
- language
- versioning
- preview/test
Mandatory security notifications cannot be disabled.
---
28. Logging and Audit
Structured logs include:
- timestamp
- level
- request/correlation
- company
- user/service
- application/plugin
- category
- message
- metadata
Categories:
- application
- security
- API
- integration
- queue
- scheduler
- update
- backup
- recovery
- audit
Audit is append-only and records business/security state changes, including before/after where appropriate.
Sensitive fields such as passwords, tokens, secrets, card numbers and authorization headers must be redacted.
---
29. Configuration and Secrets
Configuration layers:
```text
Framework defaults
→ Installation
→ Company
→ User
```
Plugin defaults remain in code; overrides are stored externally so updates do not overwrite them.
Secrets are separate from ordinary config.
Examples:
- DB credentials
- Stripe
- PayPal
- Xero
- auth/service credentials
- encryption/signing keys
- SMTP passwords
Secrets are requested by logical key through the Secrets Service.
Support encrypted local secret storage initially and future external providers.
---
30. Feature Flags
Support installation/company/user scoped feature flags.
Useful for gradual rollout, testing and disabling new behavior without removing code.
---
31. Installer
Supports:
- Web installer
- CLI installer
- unattended config-driven installation
Fresh install lifecycle:
```text
Start
→ Environment check
→ Config
→ Database
→ Generate secrets/keys
→ Core schema
→ Auth connection
→ Installation registration
→ Core System Services
→ Administrator
→ Selected Plugin Modules
→ Dependencies
→ Migrations
→ Health checks
→ Initial backup
→ Lock installer
→ Ready
```
Environment checks include:
- PHP version/extensions
- DB version
- permissions
- disk space
- writable paths
- HTTPS/network
- scheduler/worker capability
- OpenSSL
- required binaries
---
32. Update System
Local updater periodically checks Update Server.
Update transaction:
```text
Check
→ Read release metadata
→ Resolve full dependency update set
→ Compatibility checks
→ Download all packages
→ Verify signature/checksum
→ Create restore point
→ Maintenance mode if needed
→ Pause affected jobs
→ Stage packages
→ Pre-update checks
→ Update in dependency order
→ Migrations
→ Activate
→ Restart/reload workers
→ Health checks
→ Commit
```
No update proceeds if backup/restore-point creation fails.
Use staging/current/previous or equivalent controlled file-switching.
Do not overwrite live files piecemeal.
Update policies:
- manual
- download then approve
- security automatic
- fully automatic
- scheduled maintenance window
Per-plugin policies are supported.
---
33. Backup and Recovery
Restore point includes:
- framework files
- affected plugin files
- database snapshot
- plugin registry
- configuration
- migration state
- dependency lock
- version metadata
- checksums
- storage metadata reference
Backup states:
- creating
- ready
- invalid
- restoring
- restored
- failed
- expired
Automatic rollback after critical post-update failure.
Rollback restores:
- previous files
- database
- configuration
- plugin registry
- dependency lock
- workers
- prior health
---
34. Independent Emergency Recovery
Lives outside normal runtime under `recovery/`.
Must work even when:
- framework bootstrap fails
- dependencies fail
- routing fails
- plugin loader fails
- admin portal fails
- migrations are incompatible
Supports:
- list restore points
- inspect
- restore files
- restore DB
- restore config
- run health checks
- view recovery logs
Prefer CLI plus tightly restricted emergency web access.
---
35. Administration Portal
Main dashboard shows:
- framework health
- authentication
- DB
- storage
- update server
- backup status
- analytics
- queues
- scheduler
- plugin status
- security alerts
Health states:
- healthy
- degraded
- warning
- critical
- offline
- unknown
- maintenance
Plugin page shows:
- version
- manifest
- dependencies
- capabilities
- permissions
- config
- schema
- routes
- jobs
- events
- health
- update history
- logs
- storage
Dependency map must be generated from manifests.
Admin sections:
- Updates
- Backups
- Recovery
- Queues
- Scheduler
- Workflows
- Integrations
- Xero
- API credentials
- AI agents
- Users
- Companies
- Logs
- Audit
- Security
- Diagnostics
- Maintenance
- Notification Centre
Dangerous actions require strong confirmation and recent authentication.
Support temporary, scoped, audited support access.
---
36. Deployment Topology
Three logical layers:
```text
Central Shared Services
├── Authentication
├── Update Server
├── Backup Restore Server
├── Storage Server
└── Analytics Server
Individual Installation
├── Common Application Framework
├── Administration
├── Plugin Registry
├── Local DB
├── Local Queue/Workers
└── Installed Plugin Modules
Plugin Modules
└── Business functionality
```
Each installation has:
- installation_id
- name
- environment
- domain
- framework version
- public key
- status
- registration timestamp
- last seen
Core services use installation/service credentials with scopes.
Environments:
- development
- staging
- production
Development/staging must not accidentally use production payment/accounting credentials.
Central-service outages should degrade gracefully where possible.
Authentication is the most critical shared service, but existing authenticated sessions should not be destroyed merely because of a brief authentication-service outage.
---
37. Security Baseline
Mandatory:
- HTTPS
- Secure/HttpOnly/SameSite cookies
- session rotation
- CSRF for state-changing web requests
- parameterised DB access
- validation
- escaped HTML output
- secure headers
- rate limiting
- permissions/policies
- secure file validation
- encrypted secrets
- audit
- safe errors
- dependency management
- signed update packages
Production errors never expose:
- stack traces
- SQL
- credentials
- filesystem paths
- secrets
- internal config
User-facing errors should include a request reference ID.
Do not invent custom cryptography.
---
38. Coding Standards
Modern PHP conventions:
- `declare(strict_types=1);` where appropriate
- namespaces
- type declarations
- return types
- dependency injection
- interfaces
- PSR-compatible autoload/style
- small focused classes
- clear exceptions
Avoid:
- global mutable state
- giant utility classes
- business logic in templates
- DB access from views
- plugin-to-plugin includes
- hardcoded paths/URLs/credentials
- undeclared dependencies
- random third-party copied code
Preferred responsibility flow:
```text
Controller
→ Service/Application layer
→ Repository/Domain
→ Database
```
---
39. Testing
Levels:
- Unit
- Feature
- Integration
- End-to-end
Critical automated coverage:
- Authentication/SSO
- tenant isolation
- permissions/policies
- plugin install
- dependency resolution
- enable/disable
- update
- rollback
- migrations
- backup
- restore
- file permissions
- API authentication
- queue retry/idempotency
- cross-plugin workflows
- audit
Reusable tenant-isolation contract tests must prove Company A cannot access Company B records/files by manipulated IDs.
Plugin contract tests:
- manifest valid
- prefix unique
- dependencies valid
- migrations valid
- permissions register
- routes valid
- health checks
- disable behavior
- uninstall policy
- no undeclared cross-plugin DB access
CI release gate:
- syntax/lint
- coding standards
- static analysis
- unit tests
- feature tests
- integration tests
- plugin contract tests
- package validation
---
40. Accessibility and Responsive UI
Shared UI targets practical WCAG 2.1 AA principles.
Require:
- semantic HTML
- keyboard support
- labelled fields
- focus indicators
- contrast
- accessible errors
- responsive desktop/tablet/mobile design
Support current mainstream Chrome, Edge, Firefox, Safari.
---
41. Release Artifacts
Production releases are created by release tooling and include:
- version
- release manifest
- checksums
- digital signature
- release notes
- migrations
- compatibility
- rollback metadata
- health checks
Do not hand-assemble production releases as the normal workflow.
---
42. Codex Implementation Rules
The master specification is authoritative.
Codex must:
1. Read the complete specification before making architectural decisions.
2. Preserve terminology and folder boundaries.
3. Implement shared behavior in the Common Application Framework.
4. Respect plugin data ownership.
5. Respect manifest dependencies.
6. Never introduce undeclared hard dependencies.
7. Never directly query another plugin’s tables.
8. Never put uploads in plugin source folders.
9. Never keep mutable application configuration in files overwritten by updates.
10. Never store credentials in source.
11. Never weaken authentication/permissions for convenience.
12. Use migrations for schema changes.
13. Add tests with implementation.
14. Update project documentation after meaningful changes.
15. Do not invent speculative platform features.
16. Do not silently remove or simplify requirements.
17. Where requirements genuinely conflict, record the conflict in `decisions.md`.
18. Keep `todo.md`, `updates.md`, and `decisions.md` current.
---
43. Initial Implementation Sequence
Do **not** attempt to build every Plugin Module in the first implementation.
Phase 1 — Framework skeleton
- Project structure
- Bootstrap
- Config
- Database abstraction
- Logging
- Request lifecycle
Phase 2 — Identity and authorisation
- Central Authentication integration
- Company/relationship context
- Roles
- Permissions
- Policies
Phase 3 — Plugin runtime
- Manifest validation
- Discovery
- Dependency resolver
- Plugin registry
- install/enable/disable lifecycle
Phase 4 — Shared runtime services
- Events
- Queues
- Scheduler
- Storage
- PDF/documents
- Notifications
- Audit
Phase 5 — Installation and recovery
- Installer
- Updater
- Backup
- Rollback
- Emergency recovery
Phase 6 — Administration
- Admin Portal
- Diagnostics
- Health
- Integration manager
- Dependency visualisation
Phase 7 — Test Plugin Module
Create a deliberately small Test Plugin to exercise:
- manifest
- migration
- route
- permission
- service
- event
- job
- storage
- config
- health
- install
- disable
- update
- uninstall
Do not proceed to broad Plugin Module development until framework contract tests pass.
Phase 8 — First real Plugin Modules
Recommended:
1. Products
2. Asset Registry
3. ServiceVault
This tests both product/data ownership and a real hard plugin dependency.
---
44. Final Architectural Principles
1. One account can represent multiple business relationships.
2. One authoritative owner per business record.
3. Plugins do not directly reach into each other’s databases.
4. Dependencies are explicit in manifests.
5. Required dependencies stay minimal.
6. Cross-plugin writes are idempotent.
7. Cross-plugin workflows are recoverable.
8. Shared infrastructure belongs in the framework.
9. Plugin data/config/files remain separable from plugin code.
10. Every update has a tested path back.
11. Central services must not unnecessarily become single points of failure.
12. AI operates through the same controlled permission and service layers.
13. The framework is the platform contract; plugins build on it rather than bypassing it.
---
45. 2026-08-12 Commerce Status
- Products, Suppliers, E-commerce, Invoice Generation, and Payments & Billing now have a first real operational implementation path for the commerce milestone.
- This batch includes durable persistence, administration forms, secure JSON APIs, Website Builder storefront routing, public cart and checkout, invoice creation, payment tracking, audit logging, and outbox events.
- This batch does not mark Inventory Tracking, Order Processing, Asset Registry, ServiceVault, Lead Pipeline, Project Tendering, or Business Intelligence & Reporting complete; those remain preserved but intentionally out of scope.
- Stripe remains scaffolded for test-mode configuration until credentials are supplied. The development test provider is the current end-to-end checkout provider.