dev_arc_aws/docs/aws-architecture/system-design.md

# ArchNest — Self-Hosted Product Design

> Open-core model: free self-hosted base with $5 one-time module purchases.
> No subscriptions. No SaaS. Customer owns it forever.

---

## Business Model

| Aspect | Detail |
|--------|--------|
| **Core** | Free, self-hosted, open-source (or source-available) |
| **Modules** | $5 one-time purchase each (lifetime license) |
| **Updates** | Free core updates forever. Module updates included. |
| **License** | Phone-home on boot + weekly check. Works offline between checks. |
| **Revenue** | Volume × $5. Target: high module attach rate per install. |
| **Infrastructure cost** | Near zero (license server + payment processor only) |

---

## Free Core (What Ships for Free)

The free tier must be genuinely useful — good enough to adopt, limited enough
to want more.

| Feature | Included Free |
|---------|--------------|
| Dashboard (Glance page) | ✓ |
| Infrastructure overview | ✓ |
| SSH Terminal (1 tab, 1 pane) | ✓ |
| SSH Tunnels (manual start only) | ✓ |
| SFTP File Manager | ✓ |
| Docker management (TCP API only, 1 source) | ✓ |
| Host Metrics (basic: CPU/memory/disk) | ✓ |
| Bookmarks (10 max) | ✓ |
| Settings (Profile, Integrations) | ✓ |
| 3 SSH host integrations max | ✓ |
| 1 user (admin only) | ✓ |
| Single theme (ArchNest Dark) | ✓ |
| Help page | ✓ |

**Why this works:** A solo developer with 1–3 servers can use ArchNest for
free with a functional terminal, basic Docker visibility, and file management.
The moment they want split panes, more hosts, multi-user, or RDP — they buy
modules.

---

## Paid Modules ($5 Each)

### SSH Modules

| # | Module | What It Unlocks |
|---|--------|-----------------|
| 1 | **Multi-Pane Terminal** | Split panes (2/4), multiple tabs |
| 2 | **tmux Integration** | Attach to existing tmux sessions |
| 3 | **Jump-Host Chaining** | Connect through intermediary hosts (ProxyJump) |
| 4 | **Certificate Auth (OPKSSH)** | Certificate-based SSH authentication |
| 5 | **Tunnel Auto-Start** | Tunnels start automatically on boot |
| 6 | **Persistent Sessions** | Terminal sessions survive page navigation |
| 7 | **Session Recording** | Record terminal sessions to disk |
| 8 | **Host-to-Host Transfer** | Copy/move files between two SSH hosts |

### Docker Modules

| # | Module | What It Unlocks |
|---|--------|-----------------|
| 9 | **Docker over SSH** | Manage containers via `docker` CLI over SSH (no exposed socket) |
| 10 | **Docker Push Agent** | Outbound-only monitoring agent for Docker hosts |
| 11 | **Container Exec** | Interactive shell into running containers |
| 12 | **Container Detail View** | Full inspect: ports, networks, mounts, env, labels |

### Integration Modules

| # | Module | What It Unlocks |
|---|--------|-----------------|
| 13 | **Unlimited SSH Hosts** | Remove 3-host cap (unlimited integrations) |
| 14 | **Proxmox Integration** | VM/LXC management |
| 15 | **AWS Integration** | EC2 + STS resource inventory |
| 16 | **Cloudflare Integration** | DNS zones, resource listing |
| 17 | **NetBird Integration** | Mesh peers, connectivity |
| 18 | **Uptime Kuma Integration** | Monitor status/health |

### Desktop & Display Modules

| # | Module | What It Unlocks |
|---|--------|-----------------|
| 19 | **Remote Desktop (RDP)** | RDP sessions via Guacamole |
| 20 | **Remote Desktop (VNC)** | VNC sessions via Guacamole |
| 21 | **Remote Desktop (Telnet)** | Telnet sessions via Guacamole |
| 22 | **Theme: Midnight Blue** | Blue accent theme |
| 23 | **Theme: Forest** | Emerald accent theme |
| 24 | **Theme: Light** | Light mode theme |

### Platform Modules

| # | Module | What It Unlocks |
|---|--------|-----------------|
| 25 | **Multi-User** | Add users (admin/member roles, up to 10 seats) |
| 26 | **Advanced Metrics** | Full host metrics (network, processes, ports, firewall, login stats) |
| 27 | **Data Export/Import** | Backup/restore integrations + secrets + bookmarks + tunnels |
| 28 | **Audit Log** | Full activity audit log with export |
| 29 | **Unlimited Bookmarks** | Remove 10-bookmark cap |
| 30 | **Global Search** | Search across pages, integrations, bookmarks |

---

## Bundles (Discounted)

| Bundle | Modules Included | Price | Savings |
|--------|-----------------|-------|---------|
| **SSH Pro** | #1–8 (all SSH modules) | $25 | Save $15 |
| **Docker Pro** | #9–12 (all Docker modules) | $15 | Save $5 |
| **Remote Desktop** | #19–21 (RDP + VNC + Telnet) | $10 | Save $5 |
| **All Themes** | #22–24 (3 themes) | $10 | Save $5 |
| **Everything** | All 30 modules | $99 | Save $51 |

---

## Revenue Model

| Scenario | Installs/mo | Avg modules purchased | Revenue/mo |
|----------|-------------|----------------------|------------|
| Early (month 1-3) | 50 | 3 modules ($15 avg) | $750 |
| Growth (month 4-6) | 200 | 4 modules ($20 avg) | $4,000 |
| Steady (month 7-12) | 500 | 5 modules ($25 avg) | $12,500 |
| Mature (year 2) | 1,000 | 4 modules + bundles ($30 avg) | $30,000 |

**Infrastructure cost:** ~$20-30/month (license server + Stripe + domain).
**Profit margin:** ~95%+ (no SaaS hosting, no per-tenant compute).

---

## License System Architecture

### Phone-Home (Light Touch)

```
┌─────────────────────┐         ┌────────────────────────┐
│   Customer Install  │         │   License Server       │
│                     │         │   (Akamai / Cloudflare │
│   Fastify Backend   │────────▶│    Workers / Lambda)   │
│   on boot + weekly  │         │                        │
│                     │◀────────│   Returns:             │
│   Validates signed  │         │   - licensed_modules[] │
│   response locally  │         │   - valid_until (7day) │
└─────────────────────┘         │   - signature          │
                                └────────────────────────┘
```

**How it works:**
1. Customer installs ArchNest (Docker Compose or bare metal)
2. On first boot, backend calls license server with install ID
3. License server returns a signed JSON payload:
   - `modules`: list of purchased module slugs
   - `valid_until`: timestamp (7 days from now)
   - `signature`: Ed25519 signature of the payload
4. Backend validates the signature locally (public key embedded in code)
5. If signature valid and `valid_until` hasn't expired → features unlocked
6. Re-checks weekly. If server unreachable, works offline for 7 days.
7. After 7 days without a successful check → falls back to free core only

**Grace period:** 7 days offline. Generous enough for server maintenance,
network issues, etc. If someone loses internet for a week, they keep working.

### License Server Stack

| Component | Provider | Cost |
|-----------|----------|------|
| License API | Cloudflare Workers (free tier: 100K req/day) | $0 |
| Database | Cloudflare D1 (free tier: 5GB) | $0 |
| Payment | Stripe (2.9% + $0.30 per transaction) | Per-sale |
| Domain | Route 53 or Cloudflare | $1/mo |
| **Total** | | **~$1/mo + Stripe fees** |

At $5/module, Stripe takes ~$0.45 per transaction. Net per module: **$4.55**.

### Purchase Flow

```
Customer browses modules in Settings → Module Store tab
  → Clicks "Buy" → Stripe Checkout ($5)
    → Stripe webhook → License server records purchase
      → Customer's next license check returns new module
        → Feature unlocks immediately (or within minutes on next poll)
```

### Install ID Generation

- Generated on first boot: `SHA-256(machine-id + secret-key + timestamp)`
- Stored in the database
- Tied to Stripe customer on first purchase
- Transferable (customer can request a reset if they move servers)

---

## Module Enforcement (Backend)

```typescript
// Fastify plugin — runs before route handlers
const tierMiddleware = (app) => {
  app.addHook('onRequest', async (req, reply) => {
    const license = app.licenseCache; // refreshed weekly
    req.modules = license?.modules ?? [];
  });
};

// Route-level check
app.get('/api/terminal/connect', {
  preHandler: [requireModule('multi-pane-terminal')],
  handler: terminalConnect
});

function requireModule(slug: string) {
  return async (req, reply) => {
    if (!req.modules.includes(slug)) {
      reply.code(402).send({
        error: 'Module required',
        module: slug,
        price: '$5',
        purchaseUrl: `https://archnest.io/modules/${slug}`
      });
    }
  };
}
```

**Frontend enforcement:**
- Module-gated UI elements show a lock icon + "Unlock for $5" prompt
- Clicking opens the purchase flow (in-app or redirect to store)
- After purchase, UI refreshes and feature unlocks

---

## Free Core Updates

- All users get bug fixes, security patches, and core feature improvements
- Module features don't get stripped from updates — once bought, always works
- New modules may be added over time (new revenue without churning existing customers)
- Major version upgrades (v2, v3) may require a new "Everything" bundle purchase (TBD)

---

## Comparison: SaaS vs Self-Hosted Module Model

| | SaaS (old design) | Self-Hosted Modules (new) |
|---|---|---|
| Infra cost | $66-300/mo | ~$1/mo |
| Revenue model | Recurring ($2.50-12/mo) | One-time ($5/module) |
| Churn risk | High (monthly cancel) | None (one-time) |
| Support burden | High (you host it) | Low (they host it) |
| Profit margin | 60-65% | 95%+ |
| Scale limit | Your AWS bill | Their hardware |
| Customer lock-in | Subscription | Ownership (better reputation) |

---

## Tech Stack (Unchanged)

| Layer | Tech |
|-------|------|
| Frontend | React 19, Vite 8, TypeScript, Tailwind v4 |
| Backend | Fastify 5, TypeScript, SQLite (better-sqlite3) |
| Auth | Local JWT + bcrypt (self-hosted, no Cognito) |
| License | Phone-home to Cloudflare Workers |
| Payment | Stripe Checkout |
| Deploy | Docker Compose (customer's hardware) |
| CI/CD | Forgejo Actions |

---

## What Changes From Current Codebase

| Area | Current | New |
|------|---------|-----|
| Database | SQLite (stays) | SQLite (stays — no Postgres migration needed) |
| Auth | Local JWT (stays) | Local JWT (stays — no Cognito needed) |
| Multi-tenant | Not needed | Not needed (single-tenant per install) |
| License check | None | New: weekly phone-home + local signature validation |
| Module gating | None | New: Fastify middleware + frontend lock UI |
| Settings page | Current tabs | New: "Module Store" tab |
| Stripe | None | New: Stripe Checkout for purchases |

**Key insight:** This model requires almost no infrastructure changes to the
current codebase. You're adding a license middleware layer and a store UI —
not rewriting the database, auth, or deployment.

---

## Implementation Priority

### Phase 1: License Infrastructure
1. Build license server (Cloudflare Workers + D1)
2. Add license check to backend (on boot + weekly cron)
3. Add module enforcement middleware
4. Add "Module Store" tab in Settings

### Phase 2: Module Gating
1. Define module boundaries in code (which routes require which module)
2. Add lock UI to gated features in frontend
3. Free tier caps (3 hosts, 1 pane, 10 bookmarks)

### Phase 3: Purchase Flow
1. Stripe integration (Checkout, webhooks)
2. Module activation on purchase
3. Bundle discounts
4. Purchase history in Settings

### Phase 4: Distribution
1. Public Docker image on Docker Hub / GitHub Container Registry
2. Landing page with module catalog
3. Installation docs
4. Demo instance for prospects

---

## Open Decisions

| # | Question | Options |
|---|----------|---------|
| 1 | Source code visibility | Open-source (MIT/Apache) vs source-available (BSL) vs proprietary |
| 2 | Docker Hub vs self-hosted registry | Docker Hub (wider reach) vs GHCR (free private) |
| 3 | Landing page tech | Static site on Cloudflare Pages vs separate repo |
| 4 | Refund policy | 30-day no-questions vs no refunds ($5 is low enough) |
| 5 | Module store UX | In-app tab vs external website |
| 6 | License transfer | Allow unlimited vs 1 transfer per year |