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

# System Architecture

> How Cr3dentials verifies credentials with zero-knowledge proofs and cryptographic attestations without storing or accessing sensitive data.

Cr3dentials is a privacy-first credential verification platform. It uses zero-knowledge proofs and cryptographic attestations to verify credentials without storing or accessing sensitive user data.

The architecture is built so that we see nothing, store nothing, and know nothing about your private information while still producing cryptographically verifiable proofs.

## Privacy-First Design

### Core Privacy Principles

* **Cr3dentials never sees your credentials.** All verification happens through zero-knowledge proofs.
* **Zero access to sensitive data.** Our system only receives cryptographic proofs, not raw data.
* **You control what gets disclosed.** Choose exactly what to reveal and what to keep private.

### Zero-Knowledge Proof Integration

Our system verifies information without ever accessing the underlying data.

<Steps>
  <Step title="Local proof generation">
    Zero-knowledge proofs are generated on your device.
  </Step>

  <Step title="Cryptographic verification">
    We only receive mathematical proofs, never raw data.
  </Step>

  <Step title="Public attestation">
    Verifiable claims are created without exposing private information.
  </Step>
</Steps>

### Selective Disclosure Control

Cr3dentials gives you granular control over what to expose or hide.

<AccordionGroup>
  <Accordion title="Full Privacy Mode">
    Generate proofs that only confirm yes/no requirements.

    * Example: "Income > \$50k" without revealing the exact amount.
    * Bank account ownership without showing balance details.
  </Accordion>

  <Accordion title="Selective Disclosure Mode">
    Choose specific data points to reveal.

    * Example: Show monthly income but hide account numbers.
    * Reveal employment dates but keep the employer name private.
  </Accordion>

  <Accordion title="Full Transparency Mode">
    Optionally share complete verification details.

    * Useful for full background checks.
    * Still cryptographically secured and verifiable.
  </Accordion>
</AccordionGroup>

## System Architecture

### High-Level Components

<CardGroup cols={2}>
  <Card title="Client Layer">
    * Web Application (React/Next.js)
    * Mobile Application
    * User's Wallet Integration
  </Card>

  <Card title="Privacy Gateway">
    * Zero-Knowledge Proof Validator
    * Privacy Filter Layer
    * No PII Processing Zone
  </Card>

  <Card title="Cr3dentials Backend">
    * Authentication (Privy Integration)
    * Verification Module (Data Blind)
    * Attestation Service
    * Queue System for Async Processing
  </Card>

  <Card title="External Integrations">
    * Reclaim Protocol (Zero-Knowledge Engine)
    * Ethereum Attestation Service (EAS)
    * Blockchain Networks (Ethereum, L2s)
  </Card>
</CardGroup>

### Data Flow

<Steps>
  <Step title="User initiates verification">
    The request is sent through encrypted channels.
  </Step>

  <Step title="Zero-knowledge proof generation">
    Proof generation happens locally on the user's device.
  </Step>

  <Step title="Proof validation">
    Cr3dentials validates cryptographic proofs only.
  </Step>

  <Step title="Attestation creation">
    Public, verifiable claims are created on blockchain.
  </Step>

  <Step title="Verification complete">
    Results are available without exposing private data.
  </Step>
</Steps>

## Technology Stack

### Backend Infrastructure

**Framework: NestJS with Fastify**

* High-performance TypeScript framework
* Built-in validation and security features
* Module system

**Database: PostgreSQL with Prisma ORM**

* No sensitive data storage
* Only verification metadata and proofs
* Automatic migrations and type safety

**Authentication: Privy Web3 Authentication**

* Wallet-based authentication
* Traditional auth fallback
* JWT token management

**Caching: Redis**

* Session management
* Temporary proof storage
* Queue processing

### Frontend Applications

**Web Application: React with Next.js**

* Server-side rendering
* Progressive Web App capabilities
* Responsive design

**Mobile Application: React Native**

* Cross-platform compatibility
* Native performance
* Biometric authentication

### Privacy Technologies

**Zero-Knowledge Proofs**

* Mathematical privacy guarantees
* Cryptographic verification without data exposure
* Scalable proof systems

**Reclaim Protocol Integration**

* Secure credential verification from external sources
* TLS witnessing for data authenticity
* No raw data transmission to Cr3dentials

**Ethereum Attestation Service (EAS)**

* On-chain attestation creation
* Public verifiability
* Composable credential system

## Privacy Guarantees

### What We Never See

| Never Accessed          | Never Stored                     |
| ----------------------- | -------------------------------- |
| Bank account numbers    | Personal identifying information |
| Actual bank balances    | Transaction histories            |
| Social security numbers | Employment details               |
| Credit scores           | Healthcare records               |
| Personal documents      | Biometric data                   |

### What We Can Verify

| Verifiable Claims | Privacy Level            |
| ----------------- | ------------------------ |
| Account ownership | Zero-knowledge proof     |
| Income thresholds | Range verification       |
| Employment status | Boolean confirmation     |
| Age verification  | Threshold proof          |
| Identity claims   | Cryptographic validation |

## Security Architecture

### Cryptographic Security

**Transport Security**

* TLS 1.3 encryption for all communications
* Certificate pinning for API endpoints
* Perfect forward secrecy

**Proof Security**

* zk-SNARKs for zero-knowledge proofs
* Digital signatures for authenticity
* Cryptographic hashing for integrity

**Blockchain Security**

* Ethereum network security
* Audited smart contracts
* Immutable attestation records

### Attack Resistance

| Threat            | Defense                                     |
| ----------------- | ------------------------------------------- |
| Privacy attacks   | Prevented by zero-knowledge cryptography    |
| Data breaches     | Nothing to breach; no sensitive data stored |
| Man-in-the-middle | TLS encryption and certificate pinning      |
| Replay attacks    | Cryptographic nonces and timestamps         |
| Impersonation     | Digital signature verification required     |

## Integration Guides

### Creating a Privacy-First Verification

```typescript theme={null}
// Example: Income Verification with Privacy Controls
const verification = await cr3dentials.createVerification({
  type: 'income',
  privacyLevel: 'threshold', // binary | threshold | selective | full
  requirements: {
    minIncome: 50000,
    period: '3months'
  },
  disclosure: {
    showAmount: false,        // Only show yes/no
    showSource: false,        // Hide employer name
    showPeriod: true         // Show verification period
  }
});
```

### Generating Zero-Knowledge Proofs

```typescript theme={null}
// User generates proof locally - Cr3dentials never sees raw data
const proof = await reclaim.generateIncomeProof({
  requirements: verification.requirements,
  privacyLevel: verification.privacyLevel
});

// Only cryptographic proof is sent to Cr3dentials
const attestation = await cr3dentials.submitProof(proof);
```

### API Endpoints

<CodeGroup>
  ```http Authentication theme={null}
  POST /auth/login
  POST /auth/verify
  GET /auth/me
  ```

  ```http Verification Sessions theme={null}
  POST /verification/sessions/income
  GET /verification/sessions/{id}
  POST /verification/sessions/{id}/approve
  POST /verification/sessions/{id}/reject
  ```

  ```http Proof Management theme={null}
  POST /verification/initiate-verification
  POST /verification/submit-verification
  GET /verification/steps/{stepId}
  ```
</CodeGroup>

## Compliance and Regulations

### GDPR Compliance

* **Right to be forgotten:** Users control all data; nothing is stored centrally.
* **Data minimization:** Only necessary proofs are processed.
* **Consent management:** Granular permission controls.
* **Data portability:** Users own all their proofs.

### Financial Regulations

* **Privacy protection:** No storage of financial account data.
* **AML compliance:** Verified attestations for anti-money laundering.
* **KYC requirements:** Identity verification without data retention.
* **Banking regulations:** Compliance with financial privacy laws.

## Deployment Architecture

### Production Environment

* **Load balancing:** Caddy reverse proxy with SSL termination
* **Application tier:** Multiple API servers for redundancy
* **Background services:** Queue workers for async processing
* **Database tier:** PostgreSQL with read replicas
* **Caching layer:** Redis cluster for session management
* **Monitoring:** Centralized logging and metrics collection

### Scaling Considerations

* **Horizontal scaling:** Stateless API servers
* **Database scaling:** Read replicas and connection pooling
* **Cache optimization:** Distributed caching with Redis
* **Queue processing:** Parallel worker processes
* **CDN integration:** Static asset delivery

## Monitoring and Observability

**Metrics collection** covers application metrics (request latency, error rates, throughput), privacy metrics (proof generation success rates, verification times), infrastructure metrics (CPU, memory, disk), and business metrics (verification completion rates, adoption).

**Logging** covers security logs, privacy logs (proof validation events with no sensitive data), error logs, and audit logs for verification requests and attestation creation.

<Note>
  Privacy logs record proof validation events only. They never contain sensitive data.
</Note>

## Roadmap

Planned enhancements, in order of how speculative they are:

* Multi-party computation for verifications across multiple parties
* Recursive proofs for scalability on large verification sets
* Attribute-based and anonymous credentials for finer-grained disclosure
* Cross-chain universal attestations and bridge protocols
* Post-quantum cryptography preparation