# Kuwait Prepaid Card Program — Quick Start Guide

**Last Updated:** 2026-04-20  
**Current Phase:** Sprint 0 Ready  

---

## 🚀 Getting Started — Sprint 0 (0.5 day)

### What You'll Create
A new Elixir/Phoenix OTP app following the existing 29-app pattern in the umbrella.

### File Structure
```
apps/wallet_prepaid/
├── mix.exs                          ← New OTP app config
├── lib/
│   └── wallet_prepaid.ex            ← Entry point (empty for now)
│   └── wallet_prepaid/
│       └── application.ex           ← Supervision tree stub
├── test/
│   └── wallet_prepaid_test.exs       ← Smoke test
└── README.md
```

### Step 1: Create Directory
```bash
mkdir -p apps/wallet_prepaid/lib/wallet_prepaid
mkdir -p apps/wallet_prepaid/test
touch apps/wallet_prepaid/README.md
```

### Step 2: Create `mix.exs`
```elixir
defmodule WalletPrepaid.MixProject do
  use Mix.Project

  def project do
    [
      app: :wallet_prepaid,
      version: "0.1.0",
      build_path: "../../_build",
      config_path: "../../config/config.exs",
      deps_path: "../../deps",
      lockfile: "../../mix.lock",
      elixir: "~> 1.14",
      start_permanent: Mix.env() == :prod,
      deps: deps()
    ]
  end

  def application do
    [
      extra_applications: [:logger],
      mod: {WalletPrepaid.Application, []}
    ]
  end

  defp deps do
    [
      {:wallet_cards, in_umbrella: true},
      {:wallet_accounts, in_umbrella: true},
      {:wallet_ledger, in_umbrella: true},
      {:wallet_database, in_umbrella: true},
      {:wallet_merchant, in_umbrella: true},
      {:wallet_shared_kernel, in_umbrella: true},
      {:wallet_events, in_umbrella: true},
      {:wallet_observability, in_umbrella: true},
      {:nimble_csv, "~> 1.2"}
    ]
  end
end
```

### Step 3: Create `lib/wallet_prepaid.ex`
```elixir
defmodule WalletPrepaid do
  @moduledoc """
  Kuwait Prepaid Card Program domain.
  
  Manages prepaid programs, bulk card issuance, batch top-up, 
  and closed-loop merchant allowlist.
  """
end
```

### Step 4: Create `lib/wallet_prepaid/application.ex`
```elixir
defmodule WalletPrepaid.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      # Stores will be added in Sprint 2
      # ProgramStore, ProgramMerchantStore, etc.
    ]

    opts = [strategy: :one_for_one, name: WalletPrepaid.Supervisor]
    Supervisor.start_link(children, opts)
  end
end
```

### Step 5: Update Root `mix.exs`
Add to `:wallet_prepaid` to `apps/` (should be alphabetical):
```elixir
# In root mix.exs, in applications list
{:wallet_prepaid, in_umbrella: true},
```

Add `:nimble_csv` dependency to root (if not already present):
```elixir
{:nimble_csv, "~> 1.2"}
```

### Step 6: Verify
```bash
# From repo root
mix compile

# Should compile with 0 warnings
# Output: "Compiling ... wallet_prepaid ... Generated wallet_prepaid app"
```

### Success Criteria ✅
- [ ] `apps/wallet_prepaid/` directory exists
- [ ] `mix compile` completes with 0 warnings
- [ ] New app appears in umbrella deps tree
- [ ] All 30 apps compile together

---

## 📋 What Comes Next

### Sprint 1: Database Migrations (1.0 day)
- Create 6 new migration files in `apps/wallet_database/priv/repo/migrations/`
- Update 2 schemas: `User` + `Card`
- Target: All migrations apply cleanly

### Sprint 2: PrepaidProgram Domain (1.5 days)
- Create 4 ETS stores
- Create 8 commands with events
- Target: 54 tests, 0 failures

### Sprints 3–10: Features (12 days)
See full roadmap in `/docs/prepaid_card/PHASE_TRACKER.md`

---

## 📚 Key Resources

| Document | Purpose |
|----------|---------|
| **PHASE_TRACKER.md** | Sprint-by-sprint deliverables, tests, success criteria (MASTER DOC) |
| **new_gap_analysis.md** | What's missing vs. what exists (gap table, P0/P1 priorities) |
| **kuwait-prepaid-card-proposal.md** | Full technical spec, architecture, sprint breakdown |
| **prepaid_project_status.md** | Quick status for memory/future conversations |

---

## 🤔 Common Questions

**Q: Do I need to create the actual code for stores/commands now?**  
A: No, Sprint 0 only creates the app scaffold. Stores/commands go in Sprint 2.

**Q: What if I get a compile error about missing dependencies?**  
A: Run `mix deps.get` from the root to fetch all umbrella deps.

**Q: Where do tests go?**  
A: `apps/wallet_prepaid/test/wallet_prepaid/...` following existing pattern.

**Q: Should I commit Sprint 0 separately?**  
A: Yes! Commit message: `feat: scaffold wallet_prepaid app (Sprint 0)`

---

## ✅ Sprint 0 Checklist

- [ ] Created `apps/wallet_prepaid/` directory
- [ ] Wrote `mix.exs` (7 deps)
- [ ] Wrote `application.ex` (empty supervision tree)
- [ ] Wrote entry point module (`wallet_prepaid.ex`)
- [ ] Updated root `mix.exs` with new app + nimble_csv
- [ ] Ran `mix compile` — 0 warnings
- [ ] All 30 apps compile together
- [ ] Committed with message "feat: scaffold wallet_prepaid app"
- [ ] Ready for Sprint 1 (Database migrations)