MVP Architecture Plan

Beaver MVP — 10K Users

Family wealth management platform. GCP Cloud Run + Alpaca Broker API + Go monolith. Solo dev, ~$50K budget, 9 weeks to App Store.

10K

Target Users

1

Cloud Run Service

~$95

GCP / month

25

API Endpoints

9 wks

To App Store

Alpaca Handles

Your Backend

GCP Infra

iOS App

02 — Tech Stack

What We're Building With

Go monolith, lean GCP services, Alpaca as the financial backbone. Everything chosen to scale without rework.

Backend Go 1.23

Chi router (lightweight, net/http compatible)
sqlc (type-safe SQL → Go)
golang-migrate (schema versioning)
pgx v5 (PostgreSQL driver)
Modular monolith — clean package boundaries

Database PostgreSQL 16

Cloud SQL db-f1-micro (MVP) → db-custom-1-3840 (growth)
Double-entry ledger for funding events
Column-level encryption for PII (AES-256-GCM)
Alpaca tracks trades, you track deposits

Infra GCP Cloud Run

Scales to zero (MVP) → min 1 instance (growth)
Secret Manager for keys
Artifact Registry for Docker images
GitHub Actions CI/CD
No Terraform at MVP — direct gcloud

Financial Alpaca Broker API

FINRA-registered broker-dealer
Custody, KYC/AML, ACH funding
Trade execution (stocks, ETFs, fractional)
Tax lot tracking, 1099 generation
Webhook-driven state machine

Auth JWT RS256

Argon2id password hashing
15min access + 30d refresh tokens
Sessions in PostgreSQL (no Redis at MVP)
Rate limiting in-memory (single instance)

Frontend iOS SwiftUI

159 files, Clean Architecture
Protocol-based repositories (ready for backend)
6-step onboarding, fund wizards, portfolio view
All UI built — just needs API binding

03 — Architecture

MVP System Architecture

Single Cloud Run service orchestrating Alpaca Broker API. Webhook-driven state machine for all financial events.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8edff', 'primaryBorderColor': '#6c8cff', 'primaryTextColor': '#1a1a2e', 'lineColor': '#6c8cff', 'secondaryColor': '#f0fdf4', 'tertiaryColor': '#fef3c7', 'fontSize': '14px' }}}%% graph TB subgraph CLIENTS["Clients"] IOS["iOS App
(SwiftUI)"] WEB["Landing Page
(Vite + React)"] end subgraph GCP["Google Cloud Platform"] CR["Cloud Run
Go API Monolith
1 vCPU · 512MB"] SQL["Cloud SQL
PostgreSQL 16
db-f1-micro"] SM["Secret Manager
API Keys · JWT Keys"] AR["Artifact Registry
Docker Images"] end subgraph ALPACA["Alpaca Broker API"] ACC["Accounts
KYC · UGMA/UTMA"] FUND["Funding
ACH Transfers"] TRADE["Trading
Orders · Positions"] WH["Webhooks
State Changes"] end IOS -->|"HTTPS / JWT"| CR WEB -->|"Waitlist Only"| CR CR -->|"REST API"| ACC CR -->|"REST API"| FUND CR -->|"REST API"| TRADE WH -->|"POST /webhooks/alpaca"| CR CR -->|"pgx"| SQL CR -->|"at boot"| SM AR -->|"deploy"| CR style CLIENTS fill:#f5f3ff,stroke:#a78bfa,stroke-width:2px style GCP fill:#fef3c7,stroke:#fb923c,stroke-width:2px style ALPACA fill:#f0fdf4,stroke:#34d399,stroke-width:2px style CR fill:#e8edff,stroke:#6c8cff,stroke-width:2px style SQL fill:#fef3c7,stroke:#fb923c,stroke-width:2px style IOS fill:#f5f3ff,stroke:#a78bfa,stroke-width:2px

Click to zoom

04 — Alpaca Integration

What Alpaca Handles vs. What You Build

Alpaca replaces 3 mock providers at once: KYC, Custodian, and Payment. Single adapter layer in your codebase.

Alpaca Handles

Broker-Dealer License

FINRA member, SEC registered. You operate under their umbrella. SIPC insured up to $500K.

KYC/AML Verification

Built-in CIP verification. Submit user data, Alpaca runs identity checks. Webhook on approval/rejection.

ACH Funding

Link bank accounts, initiate transfers. Real money movement with webhook confirmations.

Trade Execution

Stocks, ETFs, fractional shares. Market/limit orders. Real-time positions and P&L.

Tax & Compliance

Automatic tax lot tracking (FIFO, LIFO). 1099 generation. Monthly/yearly statements.

Account Types

Individual + Custodial (UGMA/UTMA). MVP ships with UGMA/UTMA only — the core value prop.

You Build

App Auth & Users

JWT auth, user profiles, preferences. Your database, your sessions. Alpaca doesn't handle app auth.

Beneficiary Management

Family member CRUD, SSN encryption, UGMA/UTMA state rules, relationship tracking.

Fund Orchestration

Create fund → Alpaca custodial account. Allocation profiles, auto-invest logic, rebalancing.

Dashboard & Aggregation

Unified family view across all Alpaca accounts. Portfolio history, performance charts.

Notifications

Log to DB at MVP. Push (APNs), email (SendGrid), SMS (Twilio) come in Phase 2.

Audit Trail

Append-only logging via middleware on every request. Regulatory compliance from day 1.

05 — Modules

Go Package Map

11 modules total. Alpaca adapter is the single integration layer — every module talks through it.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8edff', 'primaryBorderColor': '#6c8cff', 'primaryTextColor': '#1a1a2e', 'lineColor': '#6c8cff', 'fontSize': '13px' }}}%% graph LR subgraph API["HTTP Layer (Chi Router)"] AUTH_H["auth/handler"] USER_H["user/handler"] BEN_H["beneficiary/handler"] FUND_H["fund/handler"] TXN_H["transaction/handler"] BANK_H["banking/handler"] DASH_H["dashboard/handler"] WH_H["webhook/handler"] end subgraph SERVICES["Service Layer"] AUTH_S["auth/service"] USER_S["user/service"] BEN_S["beneficiary/service"] FUND_S["fund/service"] TXN_S["transaction/service"] BANK_S["banking/service"] DASH_S["dashboard/service"] end subgraph ADAPTERS["Adapter Layer"] ALP["alpaca/
client · accounts
funding · trading
webhooks · types"] end subgraph DATA["Data Layer"] REPO["repositories/
sqlc generated"] LED["ledger/
double-entry"] AUD["audit/
append-only"] end AUTH_H --> AUTH_S USER_H --> USER_S BEN_H --> BEN_S FUND_H --> FUND_S TXN_H --> TXN_S BANK_H --> BANK_S DASH_H --> DASH_S WH_H --> ALP AUTH_S --> ALP FUND_S --> ALP TXN_S --> ALP BANK_S --> ALP DASH_S --> ALP AUTH_S --> REPO USER_S --> REPO BEN_S --> REPO FUND_S --> REPO TXN_S --> LED DASH_S --> REPO AUTH_S --> AUD USER_S --> AUD BEN_S --> AUD FUND_S --> AUD TXN_S --> AUD style API fill:#f5f3ff,stroke:#a78bfa,stroke-width:2px style SERVICES fill:#e8edff,stroke:#6c8cff,stroke-width:2px style ADAPTERS fill:#f0fdf4,stroke:#34d399,stroke-width:2px style DATA fill:#fef3c7,stroke:#fb923c,stroke-width:2px

Click to zoom

06 — API Endpoints

25 Endpoints — Every One Does Something Real

Down from 50+ in the full architecture. Alpaca handles KYC, custody, funding, and trading.

Auth 4 endpoints

POST /auth/register — Create user + Alpaca account
POST /auth/login — JWT access + refresh tokens
POST /auth/refresh — Rotate refresh token
POST /auth/logout — Invalidate session

Users 3 endpoints

GET /users/me — Profile
PUT /users/me — Update profile
PUT /users/me/financial-profile — Suitability (synced to Alpaca)

Beneficiaries 5 endpoints

GET /beneficiaries — List
POST /beneficiaries — Create
GET /beneficiaries/:id — Detail
PUT /beneficiaries/:id — Update
DELETE /beneficiaries/:id — Soft-delete

Funds 4 endpoints

GET /funds — List Alpaca accounts
POST /funds — Create → Alpaca custodial account
GET /funds/:id — Real balance from Alpaca
PUT /funds/:id/allocations — Rebalance trades

Banking & Transactions 5 endpoints

POST /banking/link — Alpaca ACH relationship
GET /banking/accounts — Linked bank accounts
POST /transactions/deposit — Alpaca ACH transfer
GET /transactions — List (Alpaca + ledger)
GET /funds/:id/allocations — Allocation targets

Dashboard & System 4 endpoints

GET /dashboard/summary — Aggregate all accounts
GET /dashboard/chart — Alpaca portfolio history
POST /webhooks/alpaca — Webhook receiver
GET /health — DB + Alpaca connectivity

Deferred to Phase 2

/identity/* (Alpaca KYC) /documents/* (Alpaca statements) /notifications/* (Push/Email) /funds/:id/performance

07 — Deposit + Auto-Invest Flow

Real Money Movement

Deposit triggers ACH transfer via Alpaca. On completion webhook, auto-invest splits across allocation targets.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8edff', 'primaryBorderColor': '#6c8cff', 'primaryTextColor': '#1a1a2e', 'lineColor': '#6c8cff', 'fontSize': '13px' }}}%% sequenceDiagram participant U as iOS App participant API as Go API (Cloud Run) participant DB as PostgreSQL participant ALP as Alpaca Broker API Note over U,ALP: 1. Link Bank Account (one-time) U->>API: POST /banking/link {routing, account} API->>ALP: POST /v1/accounts/{id}/ach_relationships ALP-->>API: ACH Relationship ID API->>DB: Store relationship API-->>U: Bank linked Note over U,ALP: 2. Deposit Money U->>API: POST /transactions/deposit {amount, fund_id} API->>ALP: POST /v1/accounts/{id}/transfers {ACH, $500} ALP-->>API: Transfer ID (status: PENDING) API->>DB: Ledger entry (status: pending) API-->>U: Deposit initiated Note over U,ALP: 3. ACH Settles (1-3 days) ALP->>API: Webhook: transfer.COMPLETE API->>DB: Update ledger (status: settled) Note over U,ALP: 4. Auto-Invest API->>DB: Get fund allocations (VTI 60%, VXUS 30%, BND 10%) API->>ALP: POST /v1/trading/accounts/{id}/orders {VTI, $300} API->>ALP: POST /v1/trading/accounts/{id}/orders {VXUS, $150} API->>ALP: POST /v1/trading/accounts/{id}/orders {BND, $50} ALP-->>API: Order filled (fractional shares) API->>DB: Log notification (deposit complete + invested)

Click to zoom

08 — Database Schema

PostgreSQL — Alpaca-Aware Schema

Every table that touches money links to an Alpaca account ID. Ledger tracks funding events only — Alpaca tracks trades.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8edff', 'primaryBorderColor': '#6c8cff', 'primaryTextColor': '#1a1a2e', 'lineColor': '#6c8cff', 'fontSize': '12px' }}}%% erDiagram users { uuid id PK text email UK text password_hash text first_name text last_name text alpaca_account_id UK text kyc_status text user_state timestamptz created_at } beneficiaries { uuid id PK uuid user_id FK text first_name text last_name text encrypted_ssn text relationship date date_of_birth text state } funds { uuid id PK uuid beneficiary_id FK text fund_type text account_type text alpaca_account_id UK text alpaca_status timestamptz created_at } fund_allocations { uuid id PK uuid fund_id FK text symbol decimal percentage } ach_relationships { uuid id PK uuid user_id FK text alpaca_relationship_id UK text bank_name text account_last4 text status } ledger_entries { uuid id PK uuid fund_id FK text alpaca_transfer_id decimal amount text status text entry_type timestamptz created_at } alpaca_webhook_log { uuid id PK text event_type text event_id UK text account_id jsonb payload boolean processed } audit_log { uuid id PK uuid actor_id text action text resource jsonb old_values jsonb new_values inet ip_address timestamptz created_at } users ||--o{ beneficiaries : "has" beneficiaries ||--o{ funds : "has" funds ||--o{ fund_allocations : "targets" funds ||--o{ ledger_entries : "tracks" users ||--o{ ach_relationships : "links"

Click to zoom

09 — Implementation Phases

9 Weeks — Zero to App Store

6 phases. Each builds on the previous. Alpaca sandbox for all development, flip to production at launch.

Phase 0

Scaffolding

Go project structure with Chi router
docker-compose with PostgreSQL
Cloud Run initial deploy
Alpaca sandbox credentials
Webhook endpoint stub
CI/CD pipeline (GitHub Actions)

3 days Week 2.5

Phase 1

Auth + User + Alpaca Accounts

Register → creates Alpaca account + KYC
Login → JWT access + refresh tokens
User profile CRUD
Webhook: account.updated → user_state
Financial profile (suitability data)

1 week Week 3.5

Phase 2

Beneficiaries + Funds

Beneficiary CRUD with SSN encryption
Fund creation → Alpaca custodial (UGMA/UTMA)
Fund type mapping by state
Allocation profile CRUD
Webhook: custodial account approved

1 week Week 4.5

Phase 3

Funding + Auto-Invest

ACH bank linking via Alpaca
Deposit → Alpaca ACH transfer
Webhook: transfer.COMPLETE → auto-invest
Dollar-based fractional orders (VTI, VXUS, BND)
Local ledger for funding events

1.5 weeks Week 6

Phase 4

Dashboard + Hardening

Real portfolio data from Alpaca positions
Family aggregation across accounts
Chart data from Alpaca portfolio history
Rate limiting, input validation
Integration tests vs Alpaca sandbox

1 week Week 7

Phase 5

Compliance + App Store

Fintech attorney compliance review
Terms, privacy policy, disclosures
Alpaca production review
iOS TestFlight with real backend
App Store submission
Flip ALPACA_BASE_URL to production

1 week + iOS binding Week 9

10 — Cost Breakdown

$50K Year 1 Budget

GCP costs scale from ~$10/mo at launch to ~$200/mo at 10K users. Most budget goes to legal and marketing.

MVP Tier

0 – 1K users

~$14 /mo GCP

Cloud Run — scales to zero (~$0-5)
Cloud SQL db-f1-micro 10GB (~$8)
Secret Manager ~$0.06
Artifact Registry ~$0.10
No Redis, no VPC, no WAF

Growth Tier

1K – 10K users

~$95 /mo GCP

Cloud Run min 1 instance, max 20 (~$20-40)
Cloud SQL db-custom-1-3840, HA (~$50-60)
Memorystore Redis 1GB (~$15)
VPC Connector e2-micro (~$7)
Add Terraform at this stage

Production Tier

10K+ users (post-raise)

~$300 /mo GCP

Cloud SQL HA + read replicas
Memorystore Standard
Cloud Armor WAF
Cloud KMS CMEK
Full gcp-infra-plan.md

Year 1 Total Budget

Category	Cost
GCP infra (12 months)	$120 – $170
Apple Developer Program	$99
Domain + Google Workspace	~$50
Compliance attorney	$5,000 – $10,000
State registrations	$1,000 – $3,000
Alpaca partnership	$0 (rev share)
Legal (terms, privacy)	$2,000 – $5,000
Marketing (Instagram/TikTok)	$5,000 – $10,000
Contingency	$15,000 – $30,000
Total Year 1	~$30,000 – $55,000

11 — Risk Register

Known Risks & Mitigations

Every risk has a concrete mitigation. Biggest blocker: Alpaca partnership approval.

Blocker Alpaca Rejects Partnership

Apply early (week 1). Backup: DriveWealth, Tradier. Partnership review takes 1-2 weeks.

High App Store Rejection

Follow Apple's financial app guidelines. Have disclaimers, compliance disclosures, attorney review before submission.

High Solo Dev Burnout

9 weeks is aggressive. Scope cut: ship without auto-invest first, add later. Core value prop still works with manual deposits.

Medium Sandbox vs. Production Differences

Use sandbox for all testing. Expect minor differences. Budget 1 week for production cutover issues.

Medium KYC Rejection Rate Too High

Good UX for data collection. Clear error messages on what to fix. Alpaca provides rejection reasons via webhook.

Medium ACH Returns (Insufficient Funds)

Handle transfer.RETURNED webhook. Reverse ledger entry. Notify user. Standard banking behavior.

Alpaca Sandbox → Production Checklist

Week 1

Apply for Broker API at alpaca.markets/broker-api

Weeks 1-8

All development against sandbox environment

Week 7-8

Attorney reviews disclosures, terms, privacy

Week 8-9

Alpaca reviews your app for compliance

Week 9-10

Flip ALPACA_BASE_URL env var to production

Week 10+

First real user with real money movement

12 — Growth Path

MVP → 10K Users → Scale

Everything in the MVP is designed to scale without rework. Phase 2 features add on top — nothing gets thrown away.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8edff', 'primaryBorderColor': '#6c8cff', 'primaryTextColor': '#1a1a2e', 'lineColor': '#6c8cff', 'fontSize': '13px' }}}%% graph LR subgraph MVP["MVP (0-1K users)"] M1["UGMA/UTMA only"] M2["ACH deposits"] M3["Auto-invest ETFs"] M4["Family dashboard"] M5["~$14/mo GCP"] end subgraph GROWTH["Growth (1K-10K users)"] G1["Add Redis"] G2["Recurring deposits"] G3["Push notifications"] G4["PDF statements"] G5["~$95/mo GCP"] end subgraph SCALE["Scale (10K+ post-raise)"] S1["529 plans (Ascensus)"] S2["Roth IRA (Forge Trust)"] S3["Trust accounts"] S4["Cloud Armor WAF"] S5["~$300/mo GCP"] end MVP -->|"validate"| GROWTH GROWTH -->|"raise"| SCALE style MVP fill:#f0fdf4,stroke:#34d399,stroke-width:2px style GROWTH fill:#e8edff,stroke:#6c8cff,stroke-width:2px style SCALE fill:#f5f3ff,stroke:#a78bfa,stroke-width:2px

Click to zoom

Phase 2 Feature Roadmap (after 1K users + raise)

529 Plans Partnership

State-administered, not brokerage. Partner with Ascensus or state plan provider. Add fivetwonine/ adapter package.

Roth IRA Partnership

Requires IRA custodian. Partner with Forge Trust, Equity Trust. Contribution limit tracking, income eligibility.

Revocable Trust Alpaca Enterprise

Limited Alpaca support. May need enterprise tier or separate custodian. Manual onboarding possible.

Recurring Deposits Cron

Cloud Scheduler → Alpaca ACH transfers. Weekly/biweekly/monthly. Dollar-cost averaging built in.

Push Notifications APNs

After TestFlight feedback. Deposit settled, order filled, rebalance needed, KYC approved.

Infrastructure Terraform

Migrate gcloud commands to Terraform modules. Add Memorystore Redis, Cloud Armor WAF, Cloud KMS.