# IQ Metaversity — Architecture (v2.0.0 · 2026-10-30)

## 1. Shape

```
 www.iqmetaversity.com  (PWA, Web3 wallet, DID)  ──┐
 nexus.iqmetaversity.com (3D campus, registry)   ──┤  HTTPS / WSS
                                                   ▼
                                     api-gateway :8080  (OpenAPI 3.1 · JWT · rate limit · CORS)
   ┌──────────┬──────────┬───────────┬───────────────┬──────────────┬──────────┬───────────┬───────────────┐
 identity   catalog   enrolment  learner-record   credentials    registry   telemetry   campus-bridge
  :8101      :8102      :8103        :8104           :8105         :8106      :8107        :8108
   └──────────┴──────────┴───────────┴───────────────┴──────────────┴──────────┴───────────┴───────────────┘
                 PostgreSQL 16 (schema per service) · Redis (nonces, sessions, presence) · NATS JetStream (events)
```

Front ends are static (Netlify). They work with **no backend** in `demo` mode (identity, enrolment, credentials and xAPI simulated in the
browser with WebCrypto) and switch to `live` by setting `IQ_CONFIG.mode = "live"` and `API_BASE` (Developers page).

## 2. Identity (Web3-first, privacy-first)

| Method | DID | Flow |
|---|---|---|
| Wallet | `did:pkh:eip155:<chain>:<address>` | EIP-4361 message → `personal_sign` → `/auth/siwe` recovers address (secp256k1), checks domain/chain/nonce/expiry |
| E-mail | `did:jwk:<browser key>` (or `did:web:…:u:<hash>`) | Magic link; only `sha256(email)` is stored |
| Anonymous | `did:jwk:<browser key>` | P-256 key generated in the browser; no personal data at all |
| Institutional SSO | `did:web:<institution>` | OIDC code + PKCE (discovery at `/.well-known/openid-configuration`) |

Sessions: HS256 JWT (15 min) + rotating refresh token (30 d, hashed at rest). Issuer identity: `did:web:www.iqmetaversity.com`
(`/.well-known/did.json`, ES256 key in `ISSUER_KEY_JWK`). Production: move to an HSM/KMS and DPoP-bound tokens.

## 3. Credentials

- **Format:** W3C VC 2.0 + Open Badges 3.0 `OpenBadgeCredential`, `achievementType: MicroCredential`, ECTS in `creditsAvailable`, EQF in `educationalLevel`, standards in `alignment`.
- **Proof:** JWS ES256 (`typ: vc+ld+json`) with the issuer key; the demo front end self-signs with the learner key and labels it *draft*.
- **Revocation:** Bitstring Status List 1.0 (`/credentials/status/1`), 131 072 entries, gzip + base64url.
- **Gate:** issuance requires `enrolment.state = completed` **and** `assessor_did` (a human). Automated grading is not possible by construction.
- **Export:** CLR 2.0 (`/credentials/clr`), Europass EDC profile (`/credentials/{id}/edc`), EBSI-compatible JSON-LD (same VC 2.0 envelope; register the issuer in an EBSI Trusted Issuers Registry to anchor).

## 4. Learner record & telemetry

- xAPI 2.0 LRS subset (`/xapi/statements`), IMS Caliper 1.2 ingest, results table written only by assessors.
- **Consent is the gate:** without `learning_analytics` consent statements are dropped with `204`. Purposes: learning_analytics, campus_presence, research_participation, service_improvement. Retention 90 days for product events; learner records until erasure.
- Erasure (`DELETE /auth/me`) cascades via NATS `subject.erased` to every service. Portability via `/telemetry/export` and `/xapi/statements`.

## 5. Catalog & enrolment

- Schools (ISCED-F), modules (ECTS, EQF, outcome, assessment, prerequisites, standards), certificates (stackable bundles).
- EU micro-credential mandatory elements endpoint per module. CASE 1.1 and OneRoster 1.2 exports for LMS/SIS interoperability; LTI 1.3 launch stub.
- Enrolment state machine: applied → enrolled → in_progress → submitted → assessed → completed (| withdrawn). Only `/assess` (assessor scope) can reach assessed/completed.

## 6. Campus (nexus.iqmetaversity.com)

- Embedded in the university site (`#campus`) via iframe; both sites share `shell/` (top bar, mega menu, footer). `postMessage` bridge: `nv:goto {district}`, `nv:hash`.
- Multi-user XR (gate G4) via `campus-bridge` WebSocket rooms: pose + presence only, pseudonymous (last 8 chars of DID), 32 per district, requires `campus_presence` consent.

## 7. Trust & compliance mapping

| Control | Implementation |
|---|---|
| EU AI Act Annex III (education) | no automated grading/admission; human assessor DID on every decision; AI drafts labelled |
| GDPR / KVKK | consent service, minimisation filter, hashed e-mail, erasure cascade, export, 90-day retention |
| ESG 2015 / ISO 21001 | catalog carries outcomes, workload, assessment, QA type; results auditable |
| WCAG 2.2 AA / EN 301 549 | front end: 2D equivalents for 3D/graph, keyboard, reduced motion |
| Security | static front end, JWT short TTL, refresh rotation, rate limit, RFC 9457 errors, no secrets in browser |

## 8. Production hardening (not done in this prototype)

KMS-backed issuer key and key rotation · DPoP · OIDC authorization endpoint implementation · SMTP provider · WAF · audit log (append-only) ·
SHACL validation of VCs · EBSI Trusted Issuer onboarding · load tests · penetration test · DPIA sign-off · accessibility audit.

## 9. Deploy

`docker compose up --build` locally. Cloud: any container platform (Fly.io, Render, Cloud Run, Kubernetes) + managed Postgres (Supabase/Neon/RDS),
managed Redis, NATS (or swap for the platform's queue). Put `api.iqmetaversity.com` in front of the gateway with TLS; set `PUBLIC_ORIGIN` and
`CAMPUS_ORIGIN` for CORS.

## 10. Source package

The full source (9 services, shared package, Docker Compose, PostgreSQL schema, tests) is delivered as `iqm-backend-2.0.0.zip` from the
Cowork session that built this site; this page hosts the OpenAPI schema and this document.