# Laconic Wallet Integration Project

## Overview

This project migrates the Laconic wallet from an iframe-based implementation to a native Next.js 15 integration within our Turborepo. The goal is to eliminate cross-origin communication issues, improve security, and leverage Clerk authentication.

## Architecture

```mermaid
graph TD
    subgraph "Frontend Application"
        A[apps/deploy-fe] --> B[Clerk Auth]
        A --> C[Wallet Integration]
    end
    
    subgraph "Monorepo Packages"
        D[services/wallet-core] --> E[Crypto Operations]
        D --> F[State Management]
        D --> G[Server Actions]
        
        H[services/ui/wallet] --> I[UI Components]
        H --> J[Connection Modals]
    end
    
    B --- K[GitHub OAuth]
    B --- L[Wallet Auth]
    
    C --> D
    C --> H
    
    L --> D
```

## Implementation Phases

### Phase 1: Core Wallet Package (Weeks 1-2)
- Create `services/wallet-core` package
- Implement core wallet functionality 
- Develop storage adapters
- Setup TypeScript interfaces

### Phase 2: UI Integration (Weeks 3-4)
- Create wallet UI components in `services/ui`
- Implement client hooks
- Connect wallet state management
- Create transaction signing UI

### Phase 3: Auth Integration (Weeks 5-6)
- Integrate with Clerk authentication
- Implement middleware protection
- Create unified auth flow
- Test complete flow

## Tech Stack

- **Frontend**: Next.js 15, React 19
- **Authentication**: Clerk with GitHub OAuth
- **State Management**: React Context + Server Components
- **Styling**: Tailwind CSS with shadcn/ui
- **Wallet**: Cosmos/Ethereum crypto
- **Validation**: Zod for type-safe schema validation
- **Security**: SIWE (Sign-In With Ethereum) standard

## Documentation References

- [Next.js 15 Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
- [Clerk Authentication](https://clerk.com/docs/references/nextjs/overview)
- [SIWE Protocol](https://docs.login.xyz/)
- [Cosmos SDK](https://docs.cosmos.network/main/architecture/adr-057-app-wiring)
- [Zod Schema Validation](https://zod.dev/)

## Migration Goals

1. **Remove iframe dependency**: Eliminate cross-origin communication issues
2. **Improve security**: Direct integration with authenticated routes
3. **Better UX**: Seamless authentication flow with GitHub and wallet
4. **Maintainability**: Proper separation of concerns in monorepo structure

## Deliverables

- `services/wallet-core` package
- Wallet UI components in `services/ui`
- Server actions for wallet operations
- Clerk integration for wallet authentication
- Comprehensive documentation

## Dependencies

- Clerk authentication setup
- Cosmos JS SDK
- Ethereum libraries
- SIWE (Sign-In With Ethereum)