Tech Stack
📚 PDL Architecture: This page covers the technical implementation stack. For the data generation architecture (PDL, generators, packages), see Architecture Overview.
System Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ PHONY - ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ╔═══════════════════════════════════════════════════════════════════╗ │
│ ║ UNIFIED CLI: phony (Foundation) ║ │
│ ╠═══════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ PURPOSE: Single tool for entire workflow (like gh, vercel) ║ │
│ ║ LICENSE: MIT (fully open source) ║ │
│ ║ DISTRIBUTION: Single binary, no dependencies ║ │
│ ║ ║ │
│ ║ OFFLINE (No Auth): ║ │
│ ║ $ phony train input.txt --locale tr_TR -o names.phony ║ │
│ ║ $ phony train data.csv --column name -o model.phony ║ │
│ ║ $ phony info model.phony # Show model metadata ║ │
│ ║ ║ │
│ ║ CLOUD (After: phony login): ║ │
│ ║ $ phony models push/pull # Cloud model library ║ │
│ ║ $ phony sync # Database sync ║ │
│ ║ $ phony mock start/deploy # Mock API ║ │
│ ║ $ phony generate --count 1M # High-speed generation (5M/s) ║ │
│ ║ ║ │
│ ║ WHY UNIFIED CLI: ║ │
│ ║ • Offline-first (training always free, no auth needed) ║ │
│ ║ • Progressive disclosure (cloud features unlock with login) ║ │
│ ║ • Language-agnostic (PHP dev, Python dev, anyone can use) ║ │
│ ║ • Single binary distribution (curl | sh install) ║ │
│ ║ • Same core reused in Cloud backend (Rust) ║ │
│ ║ ║ │
│ ╚═══════════════════════════════════════════════════════════════════╝ │
│ │
│ ╔═══════════════════════════════════════════════════════════════════╗ │
│ ║ OSS GENERATION LIBRARIES ║ │
│ ╠═══════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ PURPOSE: Generate data from .phony models (GENERATION ONLY) ║ │
│ ║ APPROACH: Pure native implementation per language ║ │
│ ║ DEVELOPMENT: AI-assisted (AI writes, human reviews) ║ │
│ ║ FORMAT: Reads .phony model format (created by Rust CLI) ║ │
│ ║ ║ │
│ ║ TIMELINE: ║ │
│ ║ ├── Year 1 Q1-Q2: PHP/Laravel (phonycloud/phony-php) ║ │
│ ║ ├── Year 2: Python (phonycloud/phony-python) ★ Revenue ║ │
│ ║ ├── Year 3: TypeScript (@phonycloud/phony) - Optional ║ │
│ ║ └── Future: Community contributions for other languages ║ │
│ ║ ║ │
│ ║ WHAT OSS PACKAGES DO: ║ │
│ ║ ├── Load .phony models (bundled or custom) ║ │
│ ║ ├── Generate data (N-gram weighted random walk) ║ │
│ ║ ├── Deterministic output (seed support) ║ │
│ ║ └── Framework integrations (Laravel, FastAPI, etc.) ║ │
│ ║ ║ │
│ ║ WHAT OSS PACKAGES DON'T DO: ║ │
│ ║ └── Training (use Rust CLI or Phony Cloud instead) ║ │
│ ║ ║ │
│ ║ PERFORMANCE: ~10-50K records/sec (good enough for typical use) ║ │
│ ║ MAINTENANCE: Community can maintain non-PHP implementations ║ │
│ ║ ║ │
│ ╚═══════════════════════════════════════════════════════════════════╝ │
│ │
│ ╔═══════════════════════════════════════════════════════════════════╗ │
│ ║ CLOUD PLATFORM ║ │
│ ╠═══════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ STACK: Nuxt + Go + Rust (3 languages) ║ │
│ ║ ║ │
│ ║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║ │
│ ║ │ NUXT │ │ GO │ │ RUST │ ║ │
│ ║ │ Dashboard │ │ Engine │ │ Core │ ║ │
│ ║ │ │ │ │ │ │ ║ │
│ ║ │ • Vue 3 │ │ • DB Sync │ │ • N-gram │ ║ │
│ ║ │ • TypeScript│ → │ • Mock API │ → │ • Train │ ║ │
│ ║ │ • Auth │ │ • Training │ │ • Generate │ ║ │
│ ║ │ • Billing │ │ • pgx (DB) │ │ • Model I/O │ ║ │
│ ║ │ │ │ │ │ │ ║ │
│ ║ └─────────────┘ └─────────────┘ └─────────────┘ ║ │
│ ║ ║ │
│ ║ RUST CORE: phony-core (via crates.io) + cloud FFI, compiled via CGO ║ │
│ ║ NO LARAVEL: Go handles all backend (sync, API, processing) ║ │
│ ║ PERFORMANCE: ~5M records/sec (Rust-powered) ║ │
│ ║ SCALE: TB-level database sync capable ║ │
│ ║ ║ │
│ ╚═══════════════════════════════════════════════════════════════════╝ │
│ │
│ ╔═══════════════════════════════════════════════════════════════════╗ │
│ ║ MONETIZATION STRATEGY ║ │
│ ╠═══════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ TRAINING: ║ │
│ ║ ├── Rust CLI: FREE, full speed, MIT licensed ║ │
│ ║ └── Phony Cloud: Paid convenience (Web UI, DB column training) ║ │
│ ║ ║ │
│ ║ GENERATION (This is where monetization happens): ║ │
│ ║ ├── OSS (Free): Native per language, ~10-50K/sec, "good enough" ║ │
│ ║ └── Cloud (Paid): Rust-powered, ~5M/sec, 50-100x faster ║ │
│ ║ ║ │
│ ║ INFRASTRUCTURE (Cloud-only): ║ │
│ ║ ├── Mock API hosting ║ │
│ ║ ├── Database Sync ║ │
│ ║ ├── Team collaboration ║ │
│ ║ └── Scheduled jobs, snapshots ║ │
│ ║ ║ │
│ ║ KEY INSIGHT: ║ │
│ ║ Training = one-time operation (free, builds trust) ║ │
│ ║ Generation = continuous operation (speed matters, monetizable) ║ │
│ ║ ║ │
│ ╚═══════════════════════════════════════════════════════════════════╝ │
│ │
└─────────────────────────────────────────────────────────────────────────┘Why This Architecture?
| Decision | Rationale |
|---|---|
| No Laravel | Go already handles sync/API; Laravel would be overhead |
| Nuxt for Dashboard | Vue familiarity (from Inertia), TypeScript, easy deploy |
| Go for Engine | Best DB libraries (pgx), great concurrency, fast HTTP |
| Rust for Core | Maximum N-gram performance, memory efficiency |
| Pure native OSS | Easy install, no binary deps, community maintainable |
| AI-assisted dev | Makes unfamiliar languages feasible |
| JSON + gzip | Native in all languages, zero external dependencies |
.phony Model Format
The .phony format is designed for maximum portability and zero external dependencies.
┌─────────────────────────────────────────────────────────────────────────┐
│ .PHONY FILE FORMAT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ FILE STRUCTURE: │
│ ═══════════════ │
│ .phony file = gzip compressed JSON │
│ │
│ Read: gzdecode(file) → json_decode() → native data structure │
│ Write: json_encode() → gzencode() → file │
│ │
│ DEBUG: │
│ $ gunzip -c model.phony | jq . │
│ $ zcat model.phony | python -m json.tool │
│ │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ WHY THIS FORMAT: │
│ ════════════════ │
│ ✓ JSON: Native in PHP, Python, JS, Go, Rust (no external deps) │
│ ✓ gzip: Native in PHP, Python, JS, Go, Rust (no external deps) │
│ ✓ Human debuggable: gunzip + jq for inspection │
│ ✓ LookupList structure: O(log n) weighted random selection │
│ ✓ Markov graph: O(1) lookup for generation │
│ │
│ SIZE EXAMPLE: │
│ ───────────── │
│ 100K N-grams: │
│ ├── Raw JSON: ~8 MB │
│ ├── Gzipped: ~2 MB (75% reduction) │
│ └── In RAM (loaded): ~10 MB (native hash maps) │
│ │
│ PERFORMANCE: │
│ ──────────── │
│ Load time (2MB file): ~50-100ms (decompress + parse) │
│ Generation: ~0.01ms per output (O(1) hash lookup) │
│ Throughput: 10-100K generations/sec │
│ │
└─────────────────────────────────────────────────────────────────────────┘Detailed Specification: For complete JSON schema, LookupList format, Element structure, and Markov chain graph details, see N-gram Models Architecture.
Format Versioning
| Version | Changes | Compatibility |
|---|---|---|
| 1 | Initial release | Current |
Future versions will maintain backward compatibility. Version field allows graceful migration.
Code Examples
PHP (Reading):
php
function loadPhonyModel(string $path): array {
$compressed = file_get_contents($path);
$json = gzdecode($compressed);
return json_decode($json, true);
}
// Usage
$model = loadPhonyModel('tr_TR/names.phony');
$tokens = $model['tokens'];
$bigrams = $model['ngrams']['2'];Python (Reading):
python
import gzip
import json
def load_phony_model(path: str) -> dict:
with gzip.open(path, 'rt', encoding='utf-8') as f:
return json.load(f)
# Usage
model = load_phony_model('tr_TR/names.phony')
tokens = model['tokens']
bigrams = model['ngrams']['2']JavaScript (Reading):
javascript
import { gunzipSync } from 'zlib';
import { readFileSync } from 'fs';
function loadPhonyModel(path) {
const compressed = readFileSync(path);
const json = gunzipSync(compressed).toString('utf-8');
return JSON.parse(json);
}
// Usage
const model = loadPhonyModel('tr_TR/names.phony');
const tokens = model.tokens;
const bigrams = model.ngrams['2'];Timeline
┌─────────────────────────────────────────────────────────────────────────┐
│ IMPLEMENTATION TIMELINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ YEAR 1 Q1-Q2: FOUNDATION │
│ ═════════════════════════ │
│ Week 1-4: Rust (phony-core + phony-cli) │
│ ├── phony-core: N-gram algorithms, model I/O │
│ ├── phony-cli: train, info, validate, stats commands │
│ ├── .phony format (gzipped JSON, zero dependencies) │
│ └── Pre-train bundled models (tr_TR, en_US, etc.) │
│ │
│ Week 5-10: PHP Generation Library (phonycloud/phony-php) │
│ ├── Load .phony models (from CLI) │
│ ├── N-gram generation (native PHP) │
│ ├── Deterministic seed support │
│ └── Pre-trained models bundled │
│ │
│ Week 11-14: Laravel Integration (phonycloud/phony-laravel) │
│ ├── Service provider, facades │
│ ├── Factory integration │
│ └── Artisan commands │
│ │
│ YEAR 1 Q3-Q4: CLOUD MVP │
│ ════════════════════════ │
│ Week 1-4: Rust (phony-core + cloud FFI + optimizations) │
│ Week 5-10: Go Engine (sync, mock API, training orchestration) │
│ Week 11-16: Nuxt Dashboard (UI, auth, billing) │
│ Week 17-20: PHP Cloud SDK (phonycloud/phony-cloud) │
│ │
│ YEAR 2: PYTHON ECOSYSTEM │
│ ═════════════════════════ │
│ Q1-Q2: Python Generation Library (pip install phony) │
│ ├── Load .phony models │
│ ├── N-gram generation (native Python) │
│ └── FastAPI/Django integrations │
│ │
│ Q3-Q4: Python Cloud SDK + Advanced Cloud Features │
│ ├── pip install phony-cloud │
│ ├── DB Sync advanced features │
│ └── Mock API stateful mode │
│ │
│ YEAR 3: TYPESCRIPT + SCALE │
│ ═════════════════════════ │
│ Q1-Q2: TypeScript Generation (npm install @phonycloud/phony) │
│ ├── Works in Node.js and browser │
│ └── TypeScript Cloud SDK │
│ │
│ Q3-Q4: Enterprise Features │
│ └── SSO, audit logs, on-premise option │
│ │
└─────────────────────────────────────────────────────────────────────────┘
VISUAL TIMELINE:
Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3
├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
YEAR 1 │Rust │ PHP │ Cloud MVP │
│ CLI │ Gen │████████████████████│
│█████│█████│ │
│ │ │ │
YEAR 2 │ │ Python Gen │ Cloud Adv │
│ │█████████████│█████████████│
│ │ │ │
YEAR 3 │ │ TypeScript │ Enterprise │
│ │█████████████│████████████│
│
💰 │ ←─── Revenue Starts ───→│←── Scale ───→Layer Details
Layer 1: Nuxt (TypeScript + Vue)
| Aspect | Detail |
|---|---|
| Purpose | Web dashboard, auth, billing UI |
| Why | Vue familiarity, TypeScript, easy deploy to Vercel |
| Tech | Nuxt 3, Vue 3, Auth.js, Stripe SDK |
Layer 2: Go Engine
| Aspect | Detail |
|---|---|
| Purpose | DB sync, Mock API server, training orchestration |
| Why | Goroutines for concurrency, memory efficiency, fast HTTP |
| Tech | Go 1.22+, pgx, go-mysql, asynq |
Layer 3: Rust Core
| Aspect | Detail |
|---|---|
| Purpose | N-gram train/generate/save/load |
| Why | Maximum performance for hot path (5M/sec) |
| Tech | Rust stable, serde_json + flate2 (gzip), FFI to Go |
Communication Flow
Nuxt ──HTTP──► Go Engine ──FFI (CGO)──► Rust CoreAI-Assisted Development
Development leverages AI agents for code generation with human review.
What AI Does Well
- Writing isolated modules with clear interfaces
- Test generation
- Boilerplate and CRUD operations
- Documentation
- Code translation between languages
What Needs Human Expertise
- Architectural decisions
- Performance optimization strategies
- Debugging complex issues
- Security review
- Production incident response
Language-Specific AI Effectiveness
| Language | AI Code Quality | Review Difficulty |
|---|---|---|
| TypeScript | ★★★★★ | Easy |
| Go | ★★★★ | Medium (readable) |
| Rust | ★★★★ | Hard (lifetimes, borrowing) |
Key Insight: AI can write Rust well, but reviewing Rust for correctness requires understanding ownership/borrowing. Go is more forgiving for reviewers.