User approves: "Up to 10 USDC per month to Merchant X"
    |
Contract auto-executes payment each cycle (if checks pass)
    |
User retains full custody until exact payment moment
    |
Cancel anytime with one click

[Merchant creates plan] → name, token, amount, interval
        |
[Subscriber subscribes] → approves spending cap
        |
[Payment execution] → transfer_from subscriber → merchant (net) + fee_collector (0.5%)
        |
[Subscriber manages] → pause / resume / cancel anytime

paycycle/
├── contracts/
│   ├── subscription/
│   │   └── src/
│   │       ├── lib.rs           # Subscription contract (create_plan, subscribe, execute_payment, etc.)
│   │       ├── types.rs         # PlanData, SubscriptionData, PlanStatus, SubscriptionStatus
│   │       ├── errors.rs        # PayCycleError enum (12 error variants)
│   │       ├── events.rs        # Contract event definitions
│   │       └── test.rs          # 12 contract tests
│   ├── token/
│   │   └── src/
│   │       ├── lib.rs           # PLC token (SEP-41): mint, burn, transfer, approve, metadata
│   │       └── test.rs          # 13 token tests
│   └── keeper/
│       └── src/
│           ├── lib.rs           # Keeper: execute_and_reward, batch_execute (5 inter-contract calls)
│           └── test.rs          # 4 keeper integration tests
├── frontend/
│   └── src/
│       ├── app/
│       │   ├── layout.tsx       # Root layout with nav, error boundary, toaster
│       │   ├── page.tsx         # Landing page
│       │   ├── dashboard/       # Dashboard with merchant/subscriber tabs
│       │   ├── plans/           # Plan creation and management
│       │   └── subscribe/       # Browse plans, manage subscriptions
│       ├── components/
│       │   ├── wallet/          # WalletProvider, ConnectButton
│       │   ├── subscription/    # CreatePlanForm, SubscribeFlow, SubscriptionCard
│       │   ├── transaction/     # TxStatus
│       │   ├── ui/              # Reusable UI primitives (button, card, skeleton, etc.)
│       │   ├── ErrorBoundary.tsx
│       │   └── MobileNav.tsx
│       ├── hooks/
│       │   ├── useSubscription.ts     # Core Soroban contract interaction hook
│       │   ├── useContractQueries.ts  # React Query wrapper hooks + mutations
│       │   ├── useWallet.ts           # Wallet context consumer
│       │   ├── useBalance.ts          # Balance fetching with React Query
│       │   └── useTokenApproval.ts    # Token approval for recurring debits
│       ├── lib/
│       │   ├── contracts.ts     # Contract addresses and token config
│       │   └── stellar.ts       # Network configuration
│       ├── types/
│       │   └── subscription.ts  # TypeScript types, intervals, error parsing
│       └── __tests__/
│           └── components.test.tsx  # 26 frontend component tests
├── .github/workflows/ci.yml    # CI pipeline (contract + frontend tests)
└── README.md

Storage Keys:
  "admin"           → Address (protocol admin)
  "fee_bps"         → u32 (fee in basis points, e.g. 50 = 0.5%)
  "fee_col"         → Address (fee collector)
  "plan_cnt"        → u64 (total plan count)
  "sub_cnt"         → u64 (total subscription count)
  ("plan", id)      → PlanData
  ("sub", id)       → SubscriptionData
  ("user_subs", addr) → Vec<u64> (user's subscription IDs)

execute_payment(subscription_id)
    |
    ├── Verify subscription is Active
    ├── Verify payment is due (current_time >= next_payment)
    ├── Load plan and verify it's Active
    ├── Check amount <= spending cap
    ├── Calculate fee (amount * fee_bps / 10000)
    ├── transfer_from(subscriber → merchant, net_amount)
    ├── transfer_from(subscriber → fee_collector, fee_amount)
    └── Update next_payment = current_time + interval

Providers (QueryClient + Wallet)
    |
    ├── useSubscription()           # Low-level contract calls (invoke/query)
    ├── useContractQueries()        # React Query wrappers with caching
    │   ├── useMerchantPlans()      # staleTime: 30s
    │   ├── useAllActivePlans()     # staleTime: 30s
    │   ├── useUserSubscriptions()  # staleTime: 15s
    │   └── Mutations (auto-invalidate on success)
    └── Pages consume hooks directly