Package Registry Architecture
Phony's Package Registry is a centralized hub for discovering, publishing, and sharing .phony packages - enabling a community-driven ecosystem of reusable data generation schemas.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ PACKAGE REGISTRY ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐│
│ │ CLI / WEB ││
│ │ phony packages search "turkish names" ││
│ │ phony packages install @phony/ecommerce-tr ││
│ │ phony packages publish ./my-package.phony ││
│ └───────────────────────────────┬─────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐│
│ │ REGISTRY API (Go) ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ││
│ │ │ Search │ │ Publish │ │ Download │ │ Access │ ││
│ │ │ Engine │ │ Pipeline │ │ Manager │ │ Control │ ││
│ │ │ │ │ │ │ │ │ │ ││
│ │ │ • Full-text │ │ • Validate │ │ • CDN edge │ │ • Scopes │ ││
│ │ │ • Filters │ │ • Scan │ │ • Caching │ │ • Tokens │ ││
│ │ │ • Ranking │ │ • Index │ │ • Metrics │ │ • Teams │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────┘│
│ │ │ │
│ ┌───────────┴──────┐ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ PostgreSQL │ │ Meilisearch │ │ S3 / CDN │ │
│ │ (Metadata) │ │ (Search) │ │ (Packages) │ │
│ │ │ │ │ │ │ │
│ │ • Package info │ │ • Full-text │ │ • .phony files │ │
│ │ • Versions │ │ • Faceted │ │ • Edge cached │ │
│ │ • Downloads │ │ • Typo-tolerant │ │ • Geo-replicated│ │
│ │ • Owners │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘Package Naming
Scopes
Packages are organized into scopes (similar to npm):
@scope/package-name@version
Examples:
@phony/ecommerce-tr@1.0.0 # Official Phony package
@phony/healthcare-us@2.1.0 # Official Phony package
@community/fintech-eu@1.0.0 # Community contributed
@acme-corp/internal@3.0.0 # Private organization package
my-local-package # Unscoped (local only)Scope Types
| Scope | Owner | Visibility | Who Can Publish |
|---|---|---|---|
@phony/* | Phony team | Public | Phony team only |
@community/* | Community | Public | Verified contributors |
@{org}/* | Organizations | Private/Public | Org members |
| Unscoped | Anyone | Local only | N/A (not publishable) |
Package Structure
Manifest (package.json)
json
{
"name": "@phony/ecommerce-tr",
"version": "1.2.0",
"description": "Turkish e-commerce data generation package",
"locale": "tr_TR",
"license": "MIT",
"author": {
"name": "Phony Team",
"email": "packages@phony.cloud"
},
"repository": {
"type": "git",
"url": "https://github.com/phonycloud/packages"
},
"keywords": ["ecommerce", "turkish", "products", "orders"],
"dependencies": {
"@phony/base-tr": "^1.0.0",
"@phony/geo-tr": "^1.0.0"
},
"exports": {
"generators": ["user", "product", "order", "payment"],
"entities": ["User", "Product", "Order", "OrderItem", "Payment"],
"models": ["product_names", "company_names", "street_names"]
},
"phony": {
"min_cli_version": "1.0.0",
"min_lib_version": {
"php": "1.0.0",
"python": "1.0.0"
}
}
}Package Contents
ecommerce-tr-1.2.0.phony
├── package.json # Manifest
├── schema.pdl.json # Main PDL schema
├── models/ # N-gram models
│ ├── product_names.ngram
│ ├── company_names.ngram
│ └── street_names.ngram
├── lists/ # Static lists
│ ├── cities.json
│ ├── categories.json
│ └── payment_methods.json
├── README.md # Documentation
└── CHANGELOG.md # Version historyPublishing Pipeline
┌─────────────────────────────────────────────────────────────────────────┐
│ PUBLISH PIPELINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. UPLOAD │
│ ══════════ │
│ phony packages publish ./my-package │
│ │ │
│ ▼ │
│ 2. VALIDATION │
│ ═════════════ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ □ package.json valid │ │
│ │ □ Version not already published │ │
│ │ □ Semantic version format │ │
│ │ □ PDL schema valid │ │
│ │ □ All model files present │ │
│ │ □ Dependencies resolvable │ │
│ │ □ No circular dependencies │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 3. SECURITY SCAN │
│ ═════════════════ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ □ No malicious patterns in models │ │
│ │ □ No excessive file sizes │ │
│ │ □ No suspicious URLs/paths │ │
│ │ □ Content policy compliance │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 4. PROCESSING │
│ ══════════════ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ • Compress and sign package │ │
│ │ • Generate checksums │ │
│ │ • Extract search metadata │ │
│ │ • Create download artifacts │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 5. PUBLISH │
│ ═══════════ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ • Upload to CDN │ │
│ │ • Update search index │ │
│ │ • Update package metadata │ │
│ │ • Invalidate caches │ │
│ │ • Send webhook notifications │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘Search Engine
Search Features
bash
# Full-text search
phony packages search "turkish ecommerce"
# Filter by locale
phony packages search --locale tr_TR
# Filter by scope
phony packages search --scope @phony
# Filter by keyword
phony packages search --keyword healthcare
# Sort options
phony packages search "names" --sort downloads
phony packages search "names" --sort recent
phony packages search "names" --sort relevanceSearch Index Structure
json
{
"id": "@phony/ecommerce-tr",
"name": "ecommerce-tr",
"scope": "@phony",
"description": "Turkish e-commerce data generation package",
"keywords": ["ecommerce", "turkish", "products", "orders"],
"locale": "tr_TR",
"version": "1.2.0",
"downloads": 12500,
"stars": 45,
"author": "Phony Team",
"published_at": "2026-01-15T10:00:00Z",
"updated_at": "2026-01-30T15:00:00Z",
"exports": {
"generators": ["user", "product", "order"],
"entities": ["User", "Product", "Order"]
}
}Ranking Algorithm
score =
relevance_score * 0.4 +
popularity_score * 0.3 +
freshness_score * 0.2 +
quality_score * 0.1
where:
relevance_score = full-text match quality
popularity_score = log10(downloads + 1) / 6
freshness_score = 1 - (days_since_update / 365)
quality_score = (has_readme + has_tests + has_examples) / 3Dependency Resolution
Version Constraints
Following semver:
json
{
"dependencies": {
"@phony/base-tr": "1.0.0", // Exact version
"@phony/geo-tr": "^1.0.0", // Compatible (1.x.x)
"@phony/common": "~1.2.0", // Patch updates (1.2.x)
"@phony/beta": ">=2.0.0-beta.1" // Pre-release
}
}Resolution Algorithm
┌─────────────────────────────────────────────────────────────────────────┐
│ DEPENDENCY RESOLUTION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ @acme/my-package@1.0.0 │
│ ├── @phony/ecommerce-tr@^1.0.0 │
│ │ ├── @phony/base-tr@^1.0.0 │
│ │ └── @phony/geo-tr@^1.0.0 │
│ │ └── @phony/base-tr@^1.0.0 ← Deduped │
│ └── @phony/base-tr@^1.2.0 ← Version conflict! │
│ │
│ RESOLUTION: │
│ ════════════ │
│ 1. Collect all version constraints │
│ 2. Find highest version satisfying all constraints │
│ 3. If conflict, report error with suggested fix │
│ │
│ Result: │
│ @phony/base-tr@1.2.0 (satisfies ^1.0.0 AND ^1.2.0) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Access Control
Visibility Levels
| Level | Who Can View | Who Can Download |
|---|---|---|
| Public | Everyone | Everyone |
| Unlisted | Link only | Anyone with link |
| Private | Org members | Org members |
| Restricted | Org + invited | Org + invited |
Token-Based Access
bash
# Generate scoped token
phony auth token create \
--name "ci-readonly" \
--scope read:packages \
--expires 90d
# Use in CI
PHONY_TOKEN=phony_xxx phony packages install @acme/internalTeam Permissions
json
{
"teams": {
"maintainers": {
"permissions": ["publish", "unpublish", "transfer"],
"members": ["user1", "user2"]
},
"contributors": {
"permissions": ["publish"],
"members": ["user3", "user4"]
},
"readers": {
"permissions": ["download"],
"members": ["*"]
}
}
}CDN Distribution
Global Edge Network
┌─────────────────────────────────────────────────────────────────────────┐
│ CDN DISTRIBUTION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Origin │ │
│ │ (S3) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Edge │ │ Edge │ │ Edge │ │
│ │ EU │ │ US │ │ APAC │ │
│ │ │ │ │ │ │ │
│ │ Frankfurt│ │ Virginia │ │ Tokyo │ │
│ │ London │ │ Oregon │ │ Sydney │ │
│ │ Paris │ │ Dallas │ │Singapore │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ CACHE STRATEGY: │
│ ════════════════ │
│ • Immutable packages: Cache forever (content-addressable) │
│ • Metadata: Cache 5 min, stale-while-revalidate │
│ • Search results: Cache 1 min │
│ │
└─────────────────────────────────────────────────────────────────────────┘Download URLs
bash
# Direct download (cached)
https://registry.phony.cloud/@phony/ecommerce-tr/-/ecommerce-tr-1.2.0.phony
# Integrity check
sha512-abc123...
# Alternative mirrors
https://eu.registry.phony.cloud/...
https://us.registry.phony.cloud/...
https://asia.registry.phony.cloud/...Analytics
Package Metrics
json
{
"package": "@phony/ecommerce-tr",
"metrics": {
"downloads": {
"total": 125000,
"last_30_days": 8500,
"last_7_days": 2100,
"today": 342
},
"versions": {
"1.2.0": 5000,
"1.1.0": 2800,
"1.0.0": 700
},
"by_country": {
"TR": 45000,
"DE": 12000,
"US": 8000
},
"by_runtime": {
"cli": 60000,
"php": 45000,
"python": 15000,
"cloud": 5000
}
}
}CLI Commands
bash
# Search packages
phony packages search <query> [--locale] [--scope] [--sort]
# View package info
phony packages info @phony/ecommerce-tr
# Install package
phony packages install @phony/ecommerce-tr
phony packages install @phony/ecommerce-tr@1.2.0
# List installed packages
phony packages list
# Update packages
phony packages update
phony packages update @phony/ecommerce-tr
# Uninstall package
phony packages uninstall @phony/ecommerce-tr
# Create new package
phony packages init my-package
# Validate package
phony packages validate ./my-package
# Publish package
phony packages publish ./my-package
# Unpublish version (within 72 hours)
phony packages unpublish @acme/my-package@1.0.0
# Transfer ownership
phony packages transfer @acme/my-package @new-owner
# Deprecate package
phony packages deprecate @acme/old-package "Use @acme/new-package instead"Implementation Phases
| Phase | Features | Timeline |
|---|---|---|
| Phase 2.1 | Basic registry, publish/install, public packages | Q3 Year 1 |
| Phase 2.2 | Search, dependencies, private packages | Q4 Year 1 |
| Phase 2.3 | Analytics, teams, advanced permissions | Q1 Year 2 |
| Phase 3 | Verified publishers, monetization, enterprise | Year 2+ |