Architecture and runtime
This guide describes how the CEDA portal is structured, how a browser request reaches a workspace, and where preview data is stored. It is an implementation-oriented companion to the workspace user guides.
The current portal preview is a Next.js application delivered through the OpenNext Cloudflare Worker. Its operational workspaces use browser-local demo state. The central identity API is implemented as a D1-backed route, but it requires its D1 binding and secrets to be configured in the deployed environment before it can operate. The technical diagrams distinguish those paths instead of presenting them as one already-live production database.
1. System context and deployment boundary
The portal and its documentation are two separately deployed web products:
- Portal: Next.js App Router, bundled for Cloudflare with OpenNext. The CEDA preview Worker is named ceda-innovation-portal. Static assets are served from the generated OpenNext assets directory.
- Workspaces: React client components render the applicant, Operations, Innovation Rules, evaluator, adjudication and administration experiences.
- Preview state: most workspace records are held in the current browser's localStorage. Uploaded document Blobs are held in IndexedDB.
- Identity API: the route at apps/web/app/api/ceda/identity/[action]/route.ts obtains a D1 binding named CEDA_DB from the Cloudflare runtime. The binding, bootstrap secret and session configuration must be provisioned separately.
- Guides: Docusaurus builds a static documentation site and publishes it to the ceda-user-guides Cloudflare Pages project. It is not a portal API or an identity provider.
This separation matters operationally: publishing the guides does not deploy portal code, and deploying the portal does not automatically rebuild the guides.
2. Request and rendering lifecycle
What this diagram means. Cloudflare terminates the public request and runs the OpenNext Worker. Next.js resolves the route and the shared CEDA shell wraps the selected workspace. In preview mode, the client gate is disabled by default. When the build-time access-enforcement flag is enabled, the shell requests the identity endpoint and uses the response to decide whether a workspace session is present.
The identity route validates server-side session records independently of the visual client gate. A browser-only toggle is not a substitute for server-side authorization on protected endpoints.
3. Preview and production data boundaries
Browser-local preview storage
- localStorage holds synthetic applicant, funding programme, workflow, form, rubric, evaluator assignment, adjudication and funding-delivery state.
- The local document store uses IndexedDB database ceda-local-document-preview, object store application-documents, and stores Blob content with file metadata.
- Browser-local records are scoped to that browser profile and origin. They are not a central operational source of truth and do not provide cross-user access control.
Server-side foundations
- The identity API reads and writes D1 through CEDA_DB.
- Migration 0002 defines organisation ownership, application scope, evidence metadata, review events, retention events and evidence access audit.
- That migration deliberately does not store document bytes or implement an object-storage adapter. Private R2 or CEDA-managed storage and server-side endpoints are still required before production evidence can be uploaded or downloaded.
- The evidence access policy in apps/web/lib/ceda/evidence-access-policy.ts is a reference policy; it is not wired into the open browser preview.
4. Shared workspace shell and navigation
How active navigation is maintained. CedaWorkspaceShell selects a navigation definition based on the current pathname. Its section links point to IDs within the corresponding workspace. The shell synchronises the highlighted item when the URL hash changes, browser history changes, the page scrolls, a nested scroll container moves, or the viewport is resized. A requestAnimationFrame guard coalesces repeated scroll events before the active section is recalculated.
This is why each sidebar anchor must match a real section ID. When adding or renaming a section, update the navigation definition and validate the target ID together.
5. Main implementation inventory
| Concern | Implementation location | Current role |
|---|---|---|
| Shared navigation and help | apps/web/components/ceda/CedaWorkspaceShell.tsx | Shared shell and section navigation |
| Operations workspace | apps/web/components/ceda/CedaOperationsWorkspace.tsx | Preview workflow and reporting surface |
| Dynamic funding enquiry form | apps/web/components/ceda/CedaFormStudio.tsx | Browser-local form definition and published snapshots |
| Applicant document bytes | apps/web/lib/ceda/local-document-store.ts | IndexedDB Blob persistence |
| Central identity endpoints | apps/web/app/api/ceda/identity/[action]/route.ts | D1-backed identity API, binding required |
| Identity schema | apps/web/migrations/ceda/0001_identity.sql | Users, invitations, sessions and audit |
| Evidence metadata schema | apps/web/migrations/ceda/0002_funding_evidence_register.sql | Production-oriented evidence data foundation |
| Evidence access reference policy | apps/web/lib/ceda/evidence-access-policy.ts | Deny-by-default policy reference |
| User guides | apps/ceda-docs | Docusaurus static site |
6. Operational implications
- Test preview changes with fictional records only. Browser-local state must not be treated as production data.
- Do not report identity or permission enforcement as live until the deployed Worker has its D1 binding, secrets and server-side checks configured and tested.
- Do not report evidence file storage as production-ready based on the SQL metadata schema alone.
- Keep workspace UI, API services, identity data, evidence metadata and evidence bytes as separately testable boundaries.
- Preserve the production boundary when adding features: client-supplied role, organisation or application IDs must never be treated as authoritative access claims.
Related implementation files
- apps/web/components/ceda/CedaWorkspaceShell.tsx
- apps/web/lib/ceda/access-mode.ts
- apps/web/lib/ceda/local-document-store.ts
- apps/web/app/api/ceda/identity/[action]/route.ts
- apps/web/wrangler.ceda-preview.jsonc
- apps/ceda-docs/docusaurus.config.js