# Kordant

**Multi-layered consumer identity protection against predatory AI-driven scams.**

Kordant combines five service domains — voice cloning detection, dark web monitoring, spam classification, property monitoring, and data broker removal — into a unified platform with web, iOS, and Android apps.

---

## The Pitch

Scammers are weaponizing AI at scale: voice clones that sound exactly like your family, hyper-personalized phishing messages that bypass filters, and synthetic identities that exploit stolen data within hours of a breach. Legacy credit monitoring is reactive — it tells you after the damage is done.

Kordant flips the model. We detect the scam _as it happens_:

- **VoicePrint** analyzes inbound calls in real time to flag synthetic AI-generated voices before you're socially engineered.
- **DarkWatch** continuously monitors dark web forums, breach databases, and data broker caches — notifying you the moment your credentials, phone, or SSN surface.
- **SpamShield** intercepts and classifies spam calls and SMS at the network level, blocking threats before they reach your phone.
- **HomeTitle** monitors county deed records for unauthorized ownership changes, liens, and fraud.
- **RemoveBrokers** automates data broker opt-out requests to remove your personal info from people-search sites.

---

## Architecture

Unified SolidStart monolith with tRPC, Drizzle ORM, and native mobile apps.

```
┌──────────────────────────────────────────────────────────────┐
│                        Clients                               │
│  Web (SolidStart) │ iOS (SwiftUI) │ Android (Compose) │ Ext  │
└────────────────────┬─────────────────────────────────────────┘
                     │  tRPC (HTTP/WS)
                     ▼
┌──────────────────────────────────────────────────────────────┐
│                   web/ (SolidStart)                          │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Frontend (SolidStart + Tailwind)                       │ │
│  │  Landing │ Auth │ Dashboard │ Service Pages             │ │
│  └─────────────────────┬───────────────────────────────────┘ │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────────────┐ │
│  │  Backend (tRPC routers)                                 │ │
│  │  auth │ user │ family │ billing │ darkwatch │           │ │
│  │  voiceprint │ spamshield │ hometitle │ removebrokers │  │ │
│  │  alerts │ reports │ notifications │ correlation        │ │
│  └─────────────────────┬───────────────────────────────────┘ │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────────────┐ │
│  │  Background Jobs (scheduler + workers)                  │ │
│  └─────────────────────┬───────────────────────────────────┘ │
└────────────────────────┼──────────────────────────────────────┘
                         │
                ┌────────▼────────┐
                │   Turso (SQLite)│
                │   + Redis       │
                └─────────────────┘
```

---

## Directory Structure

```
kordant/
├── web/                      # SolidStart monolith (frontend + tRPC backend)
│   ├── src/
│   │   ├── routes/           # Page routes (landing, auth, dashboard)
│   │   ├── components/       # UI components (primitives, layouts, widgets)
│   │   ├── server/           # tRPC routers, services, database, jobs
│   │   ├── hooks/            # Solid hooks
│   │   ├── lib/              # Shared utilities
│   │   └── theme/            # Generated design tokens
│   └── Dockerfile
├── browser-ext/              # Chrome Manifest V3 extension
├── iOS/Kordant/              # SwiftUI native iOS app
├── android/                  # Jetpack Compose native Android app
├── design-tokens/            # Brand tokens (single source of truth)
├── docs/                     # Brand guidelines, runbooks
├── scripts/                  # Build and deployment scripts
├── tasks/                    # Project task tracking
├── docker-compose.yml        # Local dev (web + redis; DB is external Turso)
├── docker-compose.prod.yml   # Production deployment
└── .github/workflows/        # CI/CD pipelines
```

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| **Language** | TypeScript (Node.js ≥22) |
| **Framework** | SolidStart (SSR + API server) |
| **API** | tRPC (type-safe RPC) |
| **Database** | Turso / SQLite (Drizzle ORM) |
| **Cache / Queue** | Redis 7 |
| **Styling** | Tailwind CSS + CSS custom properties |
| **Mobile iOS** | SwiftUI (native) |
| **Mobile Android** | Jetpack Compose (native) |
| **Extension** | Chrome Manifest V3 |
| **Auth** | JWT + session cookies |
| **Billing** | Stripe |
| **Email** | Resend |
| **Push** | Firebase Cloud Messaging + APNs |
| **SMS** | Twilio |
| **Design Tokens** | JSON → generated TS/Swift/XML |
| **CI/CD** | Vercel (web) + Docker (scheduler) |
| **Monorepo** | pnpm workspaces |
| **Testing** | Vitest |

---

## Getting Started

### Prerequisites

- Node.js >= 22.0.0
- pnpm >= 9.0.0

### Setup

```bash
# Install dependencies
pnpm install

# Copy environment variables
cp .env.example .env

# Edit .env with your Turso credentials
# DATABASE_URL=libsql://your-db.turso.io
# DATABASE_AUTH_TOKEN=your-token

# Run database migrations
pnpm db:migrate

# Start development server
pnpm dev
```

The web app runs at `http://localhost:3000`.

---

## Design Tokens

All platforms (web, iOS, Android) share the same design tokens defined in `design-tokens/`:

```
design-tokens/
├── colors.json       # Brand, semantic, background, text, border colors
├── typography.json   # Font family, scale, weights
├── spacing.json      # 4px-based spacing scale
├── shadows.json      # Elevation definitions
└── radius.json       # Border radius scale
```

Generate platform-specific code:

```bash
node scripts/generate-tokens.mjs
```

This produces:
- `web/src/theme/tokens.ts` — TypeScript constants
- `iOS/Kordant/Theme/GeneratedTokens.swift` — SwiftUI colors + spacing
- `android/.../res/values/generated_tokens.xml` — Android resources

See `docs/BRAND_GUIDELINES.md` for full brand guidelines.

---

## Deployment

| Component | Platform | Notes |
|-----------|----------|-------|
| Web app | Vercel | git push auto-deploys |
| Database | Turso (managed) | run `pnpm db:migrate` to apply schema changes |
| Background jobs | Docker on `pan` | scheduler + Redis containers |

### Setting up the Scheduler (pan server)

The background job scheduler (dark web scans, reports, etc.) runs as Docker containers on your `pan` server. Run the setup script from anywhere:

```bash
# From dev machine (SSHs into pan):
bash scripts/setup-pan.sh

# Or directly on pan:
sudo bash scripts/setup-pan.sh
```

This installs Docker + Compose, clones the repo to `/opt/kordant`, creates a systemd service, and starts the scheduler. See the script for details and the optional Gitea post-receive hook for auto-deploy on push.

### Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start web dev server |
| `pnpm build` | Build web app for production |
| `pnpm test` | Run web tests |
| `pnpm lint` | Lint web app |
| `pnpm db:migrate` | Run database migrations |
| `pnpm db:seed` | Seed database with test data |
| `pnpm build:ext` | Build browser extension |
| `node scripts/generate-tokens.mjs` | Generate platform design tokens |
| `bash scripts/setup-pan.sh` | Deploy scheduler to pan server |

---

## Subscription Tiers

| Feature | Basic (Free) | Plus ($9.99/mo) | Premium ($24.99/mo) |
|---------|:------------:|:----------------:|:-------------------:|
| Dark web scans | Limited | Unlimited | Unlimited |
| Spam detection | Basic | AI-powered | AI-powered |
| Voice cloning detection | — | Family | Family |
| SSN monitoring | — | — | ✅ |
| Home title protection | — | — | ✅ |
| Real-time blocking | — | — | ✅ |
| 24/7 support | — | — | ✅ |