222 lines
9.5 KiB
Markdown
222 lines
9.5 KiB
Markdown
# 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 | — | — | ✅ |
|