# Sharenet Passport Architecture

## Overview

The Sharenet Passport library provides a unified API for cryptographic operations and file storage that works seamlessly across both native and WASM targets. The architecture uses Rust's conditional compilation to automatically select the appropriate implementation based on the target platform.

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    Public API Surface                       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Bip39MnemonicGenerator, Ed25519KeyDeriver,          │   │
│  │ XChaCha20FileEncryptor, FileSystemStorage           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 Infrastructure Layer                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │     Crypto      │  │    Storage      │  │    RNG      │ │
│  │                 │  │                 │  │    Time     │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Target-Specific Implementations                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │        Native (std)           │       WASM          │   │
│  │ • OsRng                       │ • getrandom(js)     │   │
│  │ • File system                 │ • LocalStorage      │   │
│  │ • SystemTime                  │ • web-time          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

## Module Structure

### Core Modules
- **`domain/`**: Domain entities, traits, and error types
- **`application/`**: Use cases and application logic
- **`infrastructure/`**: Platform-specific implementations

### Infrastructure Layer
- **`infrastructure/crypto/`**: Unified cryptographic API
  - **`shared/`**: Shared utilities and constants
  - **`native/`**: Native implementations using std
  - **`wasm/`**: WASM implementations using browser APIs
- **`infrastructure/storage/`**: Unified storage API
  - **`native/`**: File system storage
  - **`wasm/`**: Browser LocalStorage
- **`infrastructure/rng/`**: Random number generation abstraction
- **`infrastructure/time/`**: Time abstraction

## Target Selection

The library automatically selects implementations based on the target architecture:

- **Native targets** (`x86_64`, `aarch64`, etc.): Use native implementations
- **WASM targets** (`wasm32-unknown-unknown`): Use WASM implementations

### Conditional Compilation

```rust
// In infrastructure/crypto/mod.rs
#[cfg(any(not(target_arch = "wasm32"), feature = "force-native"))]
mod native;

#[cfg(any(target_arch = "wasm32", feature = "force-wasm"))]
mod wasm;
```

## Optional Override Features

For testing and special cases, optional features allow manual override:

- **`force-wasm`**: Use WASM implementation even on native targets
- **`force-native`**: Use native implementation even on WASM targets

These features are mutually exclusive and will trigger a compile error if both are enabled.

## Testing Strategy

### Target-Specific Tests
- **Native tests**: Located in `src/infrastructure/crypto/native_test.rs`
- **WASM tests**: Located in `src/infrastructure/crypto/wasm_test.rs`

### Test Runners
- **Native**: Standard `cargo test`
- **WASM**: `wasm-bindgen-test-runner` configured in `.cargo/config.toml`

## Dependencies

### Target-Specific Dependencies
- **WASM-only**: `gloo-storage`, `web-time`, `getrandom` with JS feature
- **Native-only**: `getrandom` with std feature
- **Shared**: `bip39`, `ed25519-dalek`, `chacha20poly1305`

## Public API Consistency

The public API remains identical regardless of target:

```rust
// Same API on both targets
use sharenet_passport::{
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    XChaCha20FileEncryptor,
    FileSystemStorage,
};
```

## Development Workflow

### Testing Both Targets
```bash
# Test native
cargo test

# Test WASM
cargo test --target wasm32-unknown-unknown

# Test with override features
cargo test --features force-wasm
cargo test --features force-native
```

### Building for Different Targets
```bash
# Build native
cargo build

# Build WASM
cargo build --target wasm32-unknown-unknown
```

## Adding New Target-Specific Code

1. Add shared logic to the appropriate `shared/` module
2. Implement native version in `native/` module
3. Implement WASM version in `wasm/` module
4. Update the aggregator module to export the unified API
5. Add target-specific tests

## Cryptographic Consistency

All implementations produce identical cryptographic outputs for the same inputs, ensuring cross-platform compatibility.