# Workspace Restructuring Plan

## Overview

This document outlines the plan to restructure the Sharenet Passport project into a Cargo workspace with a library crate (`sharenet-passport`) and a CLI wrapper crate (`sharenet-passport-cli`). The goal is to enable reuse of the core passport functionality in multiple contexts (CLI, web/WASM, embedded) while maintaining Clean Architecture principles.

## Target Architecture

### Workspace Structure

```
sharenet-passport-creator/
├── Cargo.toml                    # Workspace manifest
├── sharenet-passport/            # Library crate (core functionality)
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── domain/
│       ├── application/
│       └── infrastructure/
├── sharenet-passport-cli/        # CLI crate (command-line interface)
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs
│       ├── cli/
│       └── interface/
└── docs/
```

## Implementation Details

### 1. Workspace Configuration

**Root `Cargo.toml`:**
```toml
[workspace]
members = ["sharenet-passport", "sharenet-passport-cli"]
resolver = "2"

[workspace.dependencies]
# Common dependencies shared across workspace members
bip39 = "2.1"
ed25519-dalek = { version = "2.1", features = ["serde"] }
chacha20poly1305 = "0.10"
hkdf = "0.12"
sha2 = "0.10"
rand = "0.8"
rand_core = "0.6"
serde = { version = "1.0", features = ["derive"] }
serde_cbor = "0.11"
thiserror = "1.0"
zeroize = { version = "1.7", features = ["zeroize_derive"] }
hex = "0.4"
```

### 2. Library Crate (`sharenet-passport`)

**Purpose**: Core passport creation, management, and verification functionality

**`sharenet-passport/Cargo.toml`:**
```toml
[package]
name = "sharenet-passport"
version = "0.1.0"
edition = "2021"
description = "Core library for Sharenet Passport creation and management"
authors = ["Your Name <your.email@example.com>"]
license = "MIT OR Apache-2.0"
repository = "https://git.sharenet.sh/your-org/sharenet-passport"

[dependencies]
# Inherit from workspace dependencies
bip39.workspace = true
ed25519-dalek.workspace = true
chacha20poly1305.workspace = true
hkdf.workspace = true
sha2.workspace = true
rand.workspace = true
rand_core.workspace = true
serde.workspace = true
serde_cbor.workspace = true
thiserror.workspace = true
zeroize.workspace = true
hex.workspace = true

[lib]
crate-type = ["cdylib", "rlib"]  # Support both native and WASM

[features]
default = ["std"]
std = []  # Standard library support
alloc = []  # No-std with alloc support
wasm = ["alloc"]  # WASM target support

[publish]
registry = "sharenet"
```

### 3. CLI Crate (`sharenet-passport-cli`)

**Purpose**: Command-line interface wrapper around the library

**`sharenet-passport-cli/Cargo.toml`:**
```toml
[package]
name = "sharenet-passport-cli"
version = "0.1.0"
edition = "2021"
description = "CLI interface for Sharenet Passport"
authors = ["Your Name <your.email@example.com>"]

[dependencies]
sharenet-passport = { path = "../sharenet-passport" }
clap = { version = "4.4", features = ["derive"] }
rpassword = "7.2"

[dev-dependencies]
assert_matches = "1.5"
tempfile = "3.8"
```

## Clean Architecture Preservation

### Domain Layer (Pure Business Logic)

**Location**: `sharenet-passport/src/domain/`

**Characteristics**:
- Pure Rust, no external dependencies
- No I/O operations
- WASM-compatible
- Contains entities, traits, and domain errors

**Key Files**:
- `entities.rs` - Core data structures (Passport, RecoveryPhrase, etc.)
- `traits.rs` - Abstract interfaces (MnemonicGenerator, KeyDeriver, etc.)
- `error.rs` - Domain-specific errors

### Application Layer (Use Cases)

**Location**: `sharenet-passport/src/application/`

**Characteristics**:
- Generic over infrastructure traits
- Orchestrates domain and infrastructure
- No concrete implementations
- Dependency injection via traits

**Key Files**:
- `use_cases.rs` - Business use cases (CreatePassport, Import, Export, etc.)
- `error.rs` - Application-specific errors

### Infrastructure Layer (Platform Implementations)

**Location**: `sharenet-passport/src/infrastructure/`

**Characteristics**:
- Concrete implementations of domain traits
- Platform-specific code
- Optional features via conditional compilation
- Separate modules for different concerns

**Key Files**:
- `crypto.rs` - Cryptographic implementations
- `storage.rs` - File system operations

## Code Organization

### Library Public API (`sharenet-passport/src/lib.rs`)

```rust
// Re-export public API
pub mod domain;
pub mod application;
pub mod infrastructure;

// Public API surface
pub use domain::entities::{Passport, RecoveryPhrase, PassportFile};
pub use domain::traits::{MnemonicGenerator, KeyDeriver, FileEncryptor, FileStorage};
pub use application::use_cases::{
    CreatePassportUseCase,
    ImportFromRecoveryUseCase,
    ImportFromFileUseCase,
    ExportPassportUseCase,
    SignCardUseCase
};
pub use infrastructure::{
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    XChaCha20FileEncryptor,
    FileSystemStorage
};
```

### CLI Entry Point (`sharenet-passport-cli/src/main.rs`)

```rust
use sharenet_passport::{
    application::use_cases::*,
    infrastructure::*,
    domain::entities::*
};

// CLI-specific code remains here
mod cli;
mod interface;

use clap::Parser;
use crate::cli::commands::{Cli, Commands};
use crate::cli::interface::CliInterface;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cli = Cli::parse();
    let interface = CliInterface::new();

    // CLI command handling
    match cli.command {
        Commands::Create { output } => {
            interface.handle_create(&output)?;
        }
        // ... other commands
    }

    Ok(())
}
```

## Feature Flags Strategy

### Library Features

- **`std`** (default): Standard library features including file I/O
- **`alloc`**: No-std with allocator support for embedded systems
- **`wasm`**: WASM-specific optimizations and bindings

### Usage Examples

**For Web/WASM Applications:**
```toml
sharenet-passport = { version = "0.1", default-features = false, features = ["wasm"] }
```

**For Embedded Systems:**
```toml
sharenet-passport = { version = "0.1", default-features = false, features = ["alloc"] }
```

**For CLI Applications:**
```toml
sharenet-passport = { version = "0.1" }  # Uses default std features
```

## Private Registry Configuration

### Cargo Configuration

Add to `~/.cargo/config.toml`:
```toml
[registries.sharenet]
index = "https://git.sharenet.sh/api/v1/crates/{crate}/index"
```

### Publishing

```bash
cd sharenet-passport
cargo publish --registry sharenet
```

## Benefits

### 1. Reusability
- **CLI**: Full command-line interface
- **Web/WASM**: Browser-based passport management
- **Embedded**: Resource-constrained environments
- **Mobile**: Native mobile applications

### 2. Maintainability
- Clear separation of concerns
- Independent versioning of library vs CLI
- Shared dependency management
- Easier testing and mocking

### 3. Deployment Flexibility
- Library can be published to private registry
- CLI can be distributed as standalone binary
- Web components can be compiled to WASM
- Embedded systems can use minimal features

### 4. Development Workflow
- Shared code changes affect all consumers
- Independent development of CLI features
- Parallel testing of different components
- Clear API boundaries

## Usage Examples

### Web Application Usage

```rust
use sharenet_passport::{
    domain::entities::Passport,
    application::use_cases::CreatePassportUseCase,
    infrastructure::{Bip39MnemonicGenerator, Ed25519KeyDeriver}
};

// Web-specific infrastructure implementations
struct WebFileEncryptor;
struct WebStorage;

impl FileEncryptor for WebFileEncryptor { /* ... */ }
impl FileStorage for WebStorage { /* ... */ }

let use_case = CreatePassportUseCase::new(
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    WebFileEncryptor,
    WebStorage,
);
```

### CLI Usage (Unchanged)

```bash
# Existing CLI commands continue to work
sharenet-passport-cli create --output my-passport.spf
sharenet-passport-cli import-recovery --output restored.spf
sharenet-passport-cli info --file passport.spf
```

## Testing Strategy

### Library Tests
- Unit tests for domain logic
- Integration tests for use cases
- WASM tests using `wasm-bindgen-test`
- Feature-flag specific tests

### CLI Tests
- End-to-end command tests
- File system integration tests
- Cross-platform compatibility tests
- User interaction tests

## Migration Considerations

### Backward Compatibility
- Existing CLI commands remain unchanged
- File formats remain compatible
- API surface remains stable
- Documentation updates minimal

### Development Impact
- Shared workspace dependencies
- Unified build process
- Consistent testing approach
- Clear separation of library vs CLI concerns

---

This restructuring enables the Sharenet Passport core functionality to be reused across multiple platforms while maintaining the Clean Architecture principles and enabling private registry publishing to git.sharenet.sh.