SD App — Next Steps

Entry point for both parties. Use /project-continue to pick up any session. Current phase: Phase A1 — FastAPI Backend | Active tasks: A1-Task-4 deployment

Claude Response — 2026-03-27

A1-Task-1 + A1-Task-2 + A1-Task-3 complete

api-design.md updated to Draft 5 (single-endpoint architecture)
A1-Task-1: packages/sd-api/ refactored to new single-endpoint architecture
A1-Task-2: All projection endpoints — IO + TL, CA + US, annual + monthly (24 tests)
A1-Task-3: Historical endpoints — IO + TL, annual + monthly (31 tests total, all passing)
STATUS.md + ROADMAP.md updated

What Was Built

Final packages/sd-api/ structure:

packages/sd-api/
├── main.py         # POST /api/v1, GET /health, GET /profiles
├── router.py       # AnalysisRouter (strategy × period × analysis_type dispatch)
├── db.py           # asset-history SQLite access (ASSET_HISTORY_DB_PATH env var)
├── profiles.py     # CA + US predefined profiles (IO + TL, 4 each)
├── schemas/
│   ├── inputs.py   # AnalysisProfile discriminated union (strategy field)
│   └── outputs.py  # AnalysisResult (summary+details for projection; historical for historical)
└── tests/
    └── test_api.py # 31 integration tests

AnalysisRouter dispatch (all combinations implemented):

interest_only × annual × projection → interest_only.calculate
interest_only × monthly × projection → interest_only_monthly.calculate
term_loan × annual × projection → term_loan.calculate
term_loan × monthly × projection → term_loan_monthly.calculate
interest_only × annual × historical → interest_only_historical.calculate_historical
interest_only × monthly × historical → interest_only_historical_monthly.calculate_historical_monthly
term_loan × annual × historical → term_loan_historical.calculate_historical
term_loan × monthly × historical → term_loan_historical_monthly.calculate_historical_monthly

Profiles: middle-income, high-income (CA/ON) + us-middle, us-high (US federal) Historical DB: reads from SQLite at ASSET_HISTORY_DB_PATH env var; 503 if unset, 404 if ticker missing

A1-Task-4 Deployment — What You Need to Do (Railway + Cloudflare)

Step 1: Create Railway account and project

Go to railway.app → New Project → Deploy from GitHub repo
Point to the monorepo; set Root Directory to packages/sd-api
Railway will auto-detect Python — confirm startCommand = "uvicorn main:app --host 0.0.0.0 --port $PORT"

Step 2: Set Railway environment variables

ASSET_HISTORY_DB_PATH=/data/asset-history.db   (if using Railway volume)

Note: The historical DB needs to be accessible at deploy time. Options:

a) Railway persistent volume mounted at /data/ (recommended for now)
b) Download DB from object storage at startup (more scalable, deferred)

Step 3: Point Cloudflare to Railway

In Railway: get the deployment URL (e.g., sd-api-production.up.railway.app)
In Cloudflare DNS: add CNAME api → sd-api-production.up.railway.app
In Cloudflare Rate Limiting: create rule api.smartdebt.ca/api/v1* → 100 req/min per IP

Step 4: Test the live deployment

curl https://api.smartdebt.ca/api/v1/health
curl -X POST https://api.smartdebt.ca/api/v1 \
  -H "Content-Type: application/json" \
  -d '{"strategy": "interest_only", "profile_id": "middle-income"}'

A1-Task-5 CI/CD: Add when ready to deploy

GitHub Actions workflow in .github/workflows/ (spec in api-design.md)
Requires: Railway token as GitHub secret, uv workspace install working in CI

Next Steps for Talbot

Review api-design.md Draft 5 — confirm response shapes look right before deployment
A1-Task-4: Deploy to Railway + configure Cloudflare (steps above — this is a Talbot task)
Decide: include ASSET_HISTORY_DB_PATH in initial deploy, or deploy without historical first?
A1-Task-5: CI/CD — set up GitHub Actions when Railway is live

Talbot Response

Earlier I asked for your opinion on the pros and cons of switching to a single API endpoint design, where all analysis parameters were embedded in an AnalysisProfile. I didn’t see your thoughts on this. Clearly this is a simple and flexible design. Are there any meaningful downsides of this approach, or is this a sound architectural pattern that is often used as a best practice?
api-design, Draft 5: looks good
I have some experience with Cloudflare, and am lightly aware of some of its offerings, some of which have generous limits. I have heard of Railway, but have almost no knowledge of its purpose. Briefly summarize each of these services and how they are used in this SD App.

Claude Response — 2026-03-27

Summary

Answered questions on single-endpoint design, Railway, and Cloudflare
No code changes — A1-Task-4 deployment remains the next action item

Single-Endpoint Design (AnalysisProfile pattern)

This is a sound pattern. It has a name: Command/Query Object pattern — you send a self-describing request object rather than encoding the operation in the URL. Large APIs (OpenAI, Stripe, Anthropic) use it exactly this way for complex, variable-parameter operations.

Genuine trade-offs to know:

Concern	Reality for SD App
HTTP caching	`POST` is never cached by browsers/CDNs. For a math API serving unique inputs, this is irrelevant — you’d never want to cache a specific user’s calculation anyway.
REST purists	Some argue that `GET /resource` is more “correct” for reads. The counter: your operation isn’t retrieving a stored resource — it’s executing a computation. `POST` is correct.
Auto-generated docs	FastAPI’s `/docs` page shows one endpoint instead of many, which makes the discriminated union harder to browse. Minor friction.
Client code	Clients must always include `strategy` — easy to forget vs. calling a named URL. A typed SDK (TypeScript) eliminates this entirely.

The main real-world downside is discoverability — a developer browsing the docs sees one endpoint instead of eight named ones. For an internal/partner API (your use case), this is immaterial. For a public API with many external developers, you’d consider named endpoints for clarity.

Bottom line: This is the right call for SD App. The matrix of strategy × period × analysis_type × geography would have created 16+ URL paths that all do essentially the same thing. One endpoint that scales automatically as new strategies are added is cleaner and more maintainable.

Railway and Cloudflare — How They Work Together for SD App

Railway is a cloud application hosting platform — think “Heroku but modern.” You connect it to a GitHub repo, it detects Python/Node/etc. automatically, builds and deploys on every push, and gives you a URL like sd-api-production.up.railway.app. It handles containers, scaling, and environment variables. Free hobby tier is sufficient for SD App’s current traffic.

Cloudflare is a DNS/CDN/security layer that sits in front of your servers. When someone requests api.smartdebt.ca, Cloudflare intercepts it, applies rate limiting / firewall rules / caching, then proxies the request to Railway. Cloudflare never runs your code — it just controls traffic flow to it.

For SD App, the stack is:

Client (browser/SvelteKit)
    ↓  HTTPS
Cloudflare  ←— dns: api.smartdebt.ca CNAME → railway URL
    ↓  rate limiting (100 req/min/IP), DDoS protection
Railway  ←— runs FastAPI, executes sd-math calculations
    ↓  reads
SQLite DB (Railway volume or object storage)

Why this split instead of Cloudflare Workers alone? Cloudflare Workers can run JavaScript/WASM at the edge, but Python with native math libraries (numpy etc.) doesn’t run there. Railway hosts real Python ASGI servers. You get Cloudflare’s edge network and security for free on top.

Cloudflare free tier covers everything you need: DNS, proxying, rate limiting, DDoS protection, SSL. Railway free hobby tier: 500 hours/month execution time (sufficient for low-traffic dev/beta).

Next Steps for Talbot

A1-Task-4: Deploy to Railway — follow the steps in the previous Claude Response
Decide on historical DB strategy for initial deploy: start without it (projection-only) or include it?
A1-Task-5: GitHub Actions CI/CD — add after Railway is live

Talbot Response

Good clarification on Railway and Cloudflare.
FYI, note that I own these domains for my $MART DEBT Coach Mission.
- SmartDebtCoach.com: foundation of education, services, tools, …
- SmartDebtApp.com: analysis of all $MART DEBT strategies, $MART DEBT Snapshot teasers, $MART DEBT micro-app embeddable components to allow simplified analysis of single strategies (I added this the ROADMAP, Future Upgrades).
- SmartDebtWealth.com: investment and credit products to accelerate wealth, like the rich do
- TalbotStevens.com: original business foundation
SmartDebtApp.com
- I considered a subdomain, like app.SmartDebtCoach.Com, but decided on having a separate site for this app. Is this the right decision?
- Is a PWA to right choice, knowing what you know of the project’s objectives? If a pwa is the right structural choice, I do prefer SvelteKit for development instead of the more popular React path, even though I know that AI tools are much better trained with the React ecosystem.
- I saw another financial app also have a desktop deployment, via Electron 32, electron-builder 25. Is there merit in considering this for SD App?
You can repeat the incomplete Next Steps for Talbot below your responses.

Claude Response — 2026-03-27

Summary

Answered domain strategy, PWA vs. alternatives, SvelteKit vs. React, Electron question

SmartDebtApp.com — Separate Domain vs. Subdomain

Yes, the right decision. A few reasons:

Brand clarity: app.SmartDebtCoach.com puts the product under the coach’s brand umbrella, which is fine early on but creates friction if the app ever grows its own reputation or gets referenced independently. A standalone domain signals “this is a product” not “this is a page on a website.”
Routing independence: Separate domains → each is an independent deployment with its own CDN zone, rate limits, and DNS config. No risk of a SvelteKit routing change on SmartDebtCoach.com bleeding into the app.
Future optionality: If SD App ever becomes a standalone SaaS offering separate from the coaching business, the branding is already clean. A subdomain is much harder to migrate from later.

The one real downside — Cloudflare requires you to manage two zones — is trivial operationally.

PWA — Right Choice?

Yes, definitively. Here’s why it fits your specific objectives:

Objective	Why PWA wins
Advisor demos on any device	Works on laptop, tablet, phone — no install required
Snapshot teasers embeddable on SmartDebtCoach.com	Static SvelteKit routes can be iframed or linked to trivially
No app store dependency	Financial tools get rejected or delayed on iOS App Store; PWA bypasses this entirely
Offline capability (future)	Service worker caching means an advisor can demo in a dead-zone boardroom
Single codebase	One SvelteKit app covers all surfaces — web, mobile browser, installable PWA

The only scenario where PWA falls short is if you need OS-level integrations (camera, notifications, local file system access) — none of which SD App needs.

SvelteKit vs. React: Your instinct is correct and you should stick with it. SvelteKit’s adapter-static produces smaller, faster bundles than React for this use case — critical when an advisor pulls up a demo on a hotel WiFi. Svelte’s reactivity model is also a better fit for financial tables where many values update together. The AI tooling gap (Cursor, Copilot) is real but narrowing fast, and for a math-forward app with established patterns, AI codegen adds less value than on a UI-heavy app. You’ll lose nothing meaningful.

Electron — Is There Merit for SD App?

No. Don’t pursue it. Here’s the honest assessment:

What Electron gives you:

A native-looking desktop app (installer, taskbar icon, OS menus)
Full local filesystem access
Offline by default

Why it doesn’t fit SD App:

PWA already does the job. Chrome/Edge let users “Install” a PWA to their desktop — it gets a taskbar icon, runs in its own window, and works offline. From the user’s perspective it looks and behaves like a native app. No Electron overhead.
Electron ships a full Chromium + Node.js runtime. A basic Electron app is 150–200MB installed. A PWA is effectively zero bytes beyond what the browser already has. For a financial demo tool, that distribution friction matters.
The app your project referenced likely serves a different use case — probably something requiring local data files, complex integrations, or corporate IT environments where browser-based tools are blocked. SD App has none of those constraints.
Maintenance cost. Electron apps need platform-specific builds (Windows, Mac, Linux), code-signing certificates (required for macOS Gatekeeper, $99/yr Apple Developer), and a CI/CD pipeline per platform. This is meaningful overhead for a solo developer.

If desktop-native ever becomes a real requirement (e.g., a compliance-sensitive advisor firm that won’t use web tools), Tauri is the modern alternative to Electron — it uses the OS’s native webview instead of bundling Chromium, so installers are ~5MB instead of 150MB. Still not needed now, but worth knowing the name.

Bottom line: PWA + SvelteKit is the right stack. No Electron.

Next Steps for Talbot

A1-Task-4: Deploy to Railway — follow the steps in the A1-Task-4 Claude Response above
Decide on historical DB strategy for initial deploy: start without it (projection-only) or include it?
A1-Task-5: GitHub Actions CI/CD — add after Railway is live