> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sphyre.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> Sphyre's implemented application, backend, storage, and blockchain architecture

# System Architecture

Sphyre is a multi-application SSI platform built around a Rust backend, three user-facing web applications, MongoDB, IPFS, and EVM smart contracts on Base Sepolia.

```mermaid theme={null}
graph TB
    ALV[Sphyre ALV<br/>Holder Wallet<br/>Next.js 15.3.1 / React 19]
    ISS[Sphyre Issuers<br/>Issuer Dashboard<br/>React 19.1]
    VER[Sphyre Verifier<br/>Verifier Portal<br/>Next.js 15.4.4 / React 18]
    API[Fortro Engine<br/>Rust Axum API]
    DB[(MongoDB)]
    IPFS[IPFS]
    BC[Base Sepolia<br/>Smart Contracts]

    ALV --> API
    ISS --> API
    VER --> API
    API --> DB
    API --> IPFS
    API --> BC
```

## Components

| Component       | Stack                                        | Role                                                                                |
| --------------- | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Fortro Engine   | Rust 2021, Axum `0.7.5`, Tokio               | Central REST API, domain logic, cryptographic workflows                             |
| Sphyre ALV      | Next.js `15.3.1`, React `19.0.0`, TypeScript | Holder wallet for credentials, consent, presentation approval                       |
| Sphyre Issuers  | React `19.1.0`, CRA, Tailwind                | Issuer dashboard for schemas, templates, issuance, revocation                       |
| Sphyre Verifier | Next.js `15.4.4`, React `18.3.1`, TypeScript | Verifier portal for presentation requests and verification history                  |
| Contracts       | Solidity / Hardhat                           | Credential, schema, consent, SSI registry, access control, meta-transaction support |

<Card title="Smart Contracts" icon="file-contract" href="/components/smart-contracts">
  Contract inventory, registry operations, roles, and Fortro Engine blockchain routes.
</Card>

## Backend Route Topology

`fortro-engine/src/api/mod.rs` mounts these groups:

```text theme={null}
/api/auth
/api/wallet
/api/issuer
/api/verifier
/api/domain
/api/did
/api/health
/api/qr
/api/admin
/api/blockchain
/api/blockchain-legacy
```

The wallet mount merges `wallet.rs`, `credential_request.rs`, and `presentation_request.rs`, so holder credential requests and holder presentation approvals live under `/api/wallet`.

## Credential Issuance Flow

```mermaid theme={null}
sequenceDiagram
    participant H as Holder Wallet
    participant I as Issuer Dashboard
    participant F as Fortro Engine
    participant DB as MongoDB
    participant IPFS as IPFS
    participant BC as Base Sepolia

    H->>F: Submit credential request
    F->>DB: Store pending request
    I->>F: Review issuer requests
    I->>F: Approve or issue credential
    F->>F: Validate schema and sign credential
    F->>IPFS: Store credential material
    F->>BC: Register credential hash
    F->>DB: Persist credential metadata
    H->>F: Fetch wallet credentials
```

## Presentation Verification Flow

```mermaid theme={null}
sequenceDiagram
    participant V as Verifier Portal
    participant H as Holder Wallet
    participant F as Fortro Engine
    participant DB as MongoDB
    participant BC as Base Sepolia

    V->>F: POST /api/verifier/requests
    F->>DB: Store presentation request
    V->>H: Display QR payload
    H->>F: Poll or load pending request
    H->>F: Approve with selected attributes
    F->>DB: Store presentation
    V->>F: POST /api/verifier/presentations/:id/verify
    F->>BC: Check anchor and revocation state
    F->>DB: Update presentation status
    F->>V: Return verification result
```

## Storage Model

MongoDB stores users, issuers, verifiers, schemas, templates, credentials, credential requests, presentation requests, presentations, consents, wallet activities, QR records, and supporting challenge/nonce records.

Credential records include:

```json theme={null}
{
  "id": "aly:uuid",
  "issuer_did": "did:alyra:issuer...",
  "owner_did": "did:alyra:holder...",
  "credential_type": "NationalID",
  "schema_id": "schema-uuid",
  "credential_preview": {},
  "anonymous_credential": null,
  "ipfs_hash": "Qm...",
  "credential_hash": "sha256hex...",
  "blockchain_tx_hash": "0x...",
  "jwt": "eyJ...",
  "status": "active",
  "bbs_signature": "...",
  "signature_type": "bbs+",
  "kyber_encrypted": true,
  "evidence_attachments": [],
  "evidence_required": [],
  "extensions": []
}
```

## Blockchain Layer

The contract workspace contains registries and helpers used by backend blockchain routes:

```text theme={null}
AccessControl.sol
ConsentRegistry.sol
CredentialRegistry.sol
ERC2771Context.sol
ISSIRegistry.sol
MinimalForwarder.sol
SSIRegistry.sol
SSIRegistryFactory.sol
SchemaRegistry.sol
```

The active API group is `/api/blockchain`; `/api/blockchain-legacy` remains mounted for older flows.

Active blockchain routes include:

```text theme={null}
POST /api/blockchain/credential/register
POST /api/blockchain/credential/revoke
GET  /api/blockchain/credential/check/:did/:credential_hash
POST /api/blockchain/schema/register
POST /api/blockchain/consent/grant
POST /api/blockchain/consent/revoke
GET  /api/blockchain/consent/check/:user_did/:verifier_did/:purpose
GET  /api/blockchain/status
```

`SSIRegistry` is the aggregate contract used by the Rust blockchain client. It composes credential, schema, consent, DID, role, and metadata operations behind the deployed registry address.