Confidentiality: This document contains proprietary technical architecture details. Do not distribute beyond authorised investors and advisors under active NDA.
1. Architecture Overview
EduCreds is built as a three-layer distributed architecture separating off-chain application logic, a trust governance layer, and on-chain immutable anchoring. This separation ensures that sensitive student data never touches public blockchain infrastructure, while cryptographic proofs and institutional identifiers are anchored immutably for independent verification.
Layer 1 — Off-Chain (Application & API)
NestJS backend microservices deployed on Azure Container Apps (centralus region). Handles all credential issuance, management, user authentication, API access, and frontend serving. PostgreSQL database for persistent storage. Redis for job queuing and caching. All student PII remains exclusively in this layer — never written to blockchain or IPFS.
Layer 2 — Trust Layer (PoIC & Governance)
AI-powered Trust Agent implementing the Proof of Institutional Credibility (PoIC) algorithm. Scores issuing institutions across multiple credibility dimensions. EVF (EduCreds Verification Framework) provides 5-collector independent evidence verification. Governance controls manage the institutional DID registry and revocation policies. This layer is EduCreds' primary proprietary differentiation.
Layer 3 — On-Chain (EVM Smart Contracts & IPFS)
EVM-compatible smart contracts anchor credential hashes, Institution Identity Numbers (IINs, as ERC-721 tokens), revocation status flags, and IPFS content URIs. IPFS/Pinata stores credential metadata and public documents. No personally identifiable information (names, emails, grades, biometrics) is ever written to any on-chain or IPFS layer. Currently deployed on testnet; mainnet deployment pending production readiness.
2. Microservices Architecture
| Service | Role | Technology | Status |
|---|---|---|---|
| Backend API | Core platform — authentication, credential management, institution admin, API gateway for all client interactions | NestJS, TypeScript, PostgreSQL | ✅ Deployed |
| Trust Agent | PoIC scoring engine — evaluates institutional credibility, computes trust scores, performs risk analysis on credential requests | AI/ML stack + NestJS | ✅ Deployed |
| EVF (Verification Framework) | Independent 5-collector verification — aggregates evidence from multiple sources to verify credential authenticity beyond cryptographic proof | NestJS, TypeScript | ✅ Deployed |
| SD-JWT Adapter | Selective disclosure — implements IETF SD-JWT standard enabling students to share only required credential fields with verifiers | NestJS, TypeScript | ✅ Deployed |
| OID4VC Adapter | Wallet interoperability — implements OpenID for Verifiable Credentials (issuance and presentation) for compatibility with any OID4VC wallet | NestJS, TypeScript | ✅ Deployed |
| Verifier Agent | Employer-side verification — provides verification portal, QR code verification flow, API for employer systems, returns EVF report + PoIC score | NestJS, TypeScript | ✅ Deployed |
| Redis | Job queue broker and cache — manages background job queues (bulk credential issuance, blockchain transactions), application-level caching | Redis | ✅ Deployed |
3. Infrastructure
| Component | Service | Purpose | Notes |
|---|---|---|---|
| Compute | Azure Container Apps (centralus) | Serverless container hosting for all 7 microservices with auto-scaling | Microsoft for Startups Azure credits active |
| Database | Azure PostgreSQL Flexible Server | Primary relational data store — institutions, credentials, users, audit logs | Geo-redundant backup enabled |
| Secrets Management | Azure Key Vault | All cryptographic keys, API secrets, signing keys — no hardcoded credentials anywhere in codebase | RBAC-controlled access per service identity |
| Observability | Azure Application Insights | Distributed tracing, performance monitoring, error tracking, audit log aggregation | 90-day log retention configured |
| Decentralised Storage | IPFS / Pinata | Persistent storage for credential metadata, public institution documents, DID documents | PII is NOT stored on IPFS; only public metadata |
| Message Queue | Redis (via Azure Cache for Redis) | Async job queue for bulk issuance, blockchain writes, notification delivery | Managed Redis instance |
4. Security Model
Request Authentication
- HMAC-signed requests: All inter-service API calls use HMAC-SHA256 signatures with rotating secrets — prevents replay attacks and service impersonation
- mTLS (optional): Mutual TLS available for high-security Tier 1 enterprise deployments requiring service-to-service certificate-based authentication
- JWT authentication: All user-facing API calls authenticated via short-lived JWT access tokens (ES256) with refresh token rotation
Key and Credential Management
- Azure Key Vault: All signing keys, API secrets, and cryptographic material stored in Key Vault — never in environment variables or code
- ES256 credential signing: All W3C VCs signed with ES256 (ECDSA P-256) — industry standard for W3C VC proof
- Key rotation policy: Signing keys rotate on a defined schedule; revocation records updated automatically
Audit and Compliance
- Append-only audit logs: All credential issuance, verification, and revocation events written to immutable audit log stream via Application Insights
- 90-day log retention: Configurable retention per customer tier; Tier 1 supports extended retention periods
- Zero PII in logs: Development and security policy prohibits writing student names, emails, or grades to any log output
5. On-Chain Data Policy
Privacy Commitment: Student personally identifiable information is NEVER written to any public blockchain or IPFS. This is an architectural constraint, not a configuration option. The EduCreds platform anchors only cryptographic hashes and public identifiers on-chain.
| Data Element | On-Chain? | Rationale |
|---|---|---|
| Credential content hash (SHA-256) | ✓ Yes — anchored | Enables tamper-detection without revealing credential content |
| Institution Identity Number (IIN, ERC-721 token) | ✓ Yes — anchored | Non-fungible institution identifier enabling trustless issuer verification |
| Revocation status flag | ✓ Yes — anchored | Allows any verifier to check revocation without querying EduCreds API |
| IPFS content URI (metadata CID) | ✓ Yes — anchored | Points to public credential metadata (template, schema) on IPFS |
| Student name | ✗ Never on-chain | PII — stored only in encrypted off-chain database |
| Student email address | ✗ Never on-chain | PII — stored only in encrypted off-chain database |
| Grades or assessment results | ✗ Never on-chain | Sensitive academic data — off-chain only; accessible via selective disclosure with student consent |
| Biometric data | ✗ Never on-chain | Not collected or stored by EduCreds platform at all |
| National ID numbers | ✗ Never on-chain | PII — not collected; only internal student identifier used |
6. Standards Compliance
| Standard | Version | Body | Compliance Level | Use in Platform |
|---|---|---|---|---|
| W3C Verifiable Credentials | v2.0 | W3C | Full | All credential issuance and verification |
| W3C Decentralised Identifiers (DID) | v1.0 + did:educreds method | W3C | Full + proprietary DID method | Institution and subject identifiers |
| OpenID for Verifiable Credentials (OID4VC) | Draft 13 | OpenID Foundation | Full (issuance + presentation) | Wallet interoperability |
| SD-JWT (Selective Disclosure JWT) | IETF Draft | IETF | Full | Privacy-preserving credential sharing |
| ERC-721 (Non-Fungible Token) | EIP-721 | Ethereum Foundation | Full | Institution Identity Number (IIN) token |
| Uganda Data Protection and Privacy Act | 2019 | Uganda Government | Design-compliant | Data processing architecture, privacy policy |