# GlyphOS Infrastructure Plan

## Executive Summary

Proposing a production-grade infrastructure for the 600-glyph monument system. Current prototype (Rust/Axum + JSON files) needs database, auth, observability, and deployment pipeline.

---

## 1. Data Layer

### Current State
- JSON files in `glyphs/*.json`
- Meta-glyph archive: `glyph-complete-600.json` (not yet present)
- In-memory `HashMap` with RwLock

### Proposed Infrastructure

```
┌─────────────────────────────────────────────────────────┐
│                    Data Layer                           │
├─────────────────────────────────────────────────────────┤
│  Primary DB: PostgreSQL 16                              │
│  - glyphs table (600 rows, canonical + semantic)        │
│  - meta_glyphs table (600 rows, full JSONB archive)     │
│  - lineage table (60 lineages, 6 super-families)        │
│  - hash_index table (FNV-1a → glyph_id mapping)         │
│                                                         │
│  Cache: Redis                                           │
│  - LRU cache for hot glyphs (TTL: 5min)                 │
│  - Search index cache (TTL: 1min)                       │
│  - Session/rate-limit counters                          │
│                                                         │
│  Search: Meilisearch (or Elasticsearch)                 │
│  - Full-text search across name, meaning, tags          │
│  - Fuzzy matching, typo tolerance                       │
│  - Lineage/band/period filtering                        │
└─────────────────────────────────────────────────────────┘
```

**Why PostgreSQL?**
- JSONB for meta-glyph archive (flexible schema)
- ACID compliance for glyph uploads
- Row-level locking (better than RwLock contention)

---

## 2. API Layer Enhancements

### Current Endpoints (12 total)
- Health, sample, list, get-by-id, search, reload, stats, upload
- Meta-glyph: list, get, search, project

### Proposed Additions

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/glyph/{id}/resonance` | GET | Compute resonance with other glyphs |
| `/glyph/batch` | POST | Bulk upload (10-100 glyphs) |
| `/lineage/{id}` | GET | Get all glyphs in lineage |
| `/lineage/{id}/activate` | POST | Activate entire lineage cluster |
| `/meta-glyph/{id}/diff` | GET | Compare meta vs projected |
| `/admin/backup` | POST | Trigger DB backup |
| `/admin/restore` | POST | Restore from backup |

### Authentication Middleware
```rust
// Proposed auth flow
1. API key in `X-API-Key` header
2. Rate limiting: 100 req/min per key
3. Upload endpoints require admin scope
4. JWT for user sessions (optional)
```

---

## 3. Infrastructure Diagram

```
                    ┌───────────────┐
                    │   Cloudflare  │
                    │   (CDN + SSL) │
                    └───────┬───────┘
                            │
                    ┌───────▼───────┐
                    │   Kong/API    │
                    │   Gateway     │
                    │   (Auth + RL) │
                    └───────┬───────┘
                            │
 ┌───────────────┼───────────────┐
            │               │               │
    ┌───────▼───────┐ ┌────▼─────┐ ┌──────▼──────┐
    │   Glyph API   │ │ Monitor  │ │   Backup    │
    │   (Rust/Axum) │ │ Service  │ │   Service   │
    │   Port 3000   │ │ (Prometheus)│ │ (Scheduled) │
    └───────┬───────┘ └───────────┘ └──────────────┘
            │
    ┌───────┴───────┐
    │   PostgreSQL  │
    │   + Redis     │
    │   + Meilisearch│
    └───────────────┘
```

---

## 4. Deployment Architecture

### Containerization
```dockerfile
# Multi-stage build
FROM rust:1.80 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:12-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/glyph_backend /usr/local/bin
EXPOSE 3000
CMD ["glyph_backend"]
```

### Orchestration (Kubernetes)
```yaml
# Deployment
replicas: 3
resources:
  requests: { cpu: "500m", memory: "512Mi" }
  limits: { cpu: "2", memory: "2Gi" }

# HPA (Horizontal Pod Autoscaler)
minReplicas: 3
maxReplicas: 10
targetCPUUtilization: 70%

# Pod Disruption Budget
minAvailable: 2
```

### CI/CD Pipeline
```
GitHub → Actions → Build → Test → Docker → Deploy
         ├─ cargo test
         ├─ cargo clippy
         ├─ cargo fmt --check
         ├─ Integration tests (glyph upload/search)
         └─ Security scan (cargo audit)
```

---

## 5. Observability Stack

### Metrics (Prometheus + Grafana)
- Request rate per endpoint
- Response latency (p50, p95, p99)
- Glyph cache hit rate
- DB connection pool usage
- Error rate by endpoint

### Logging (Loki or ELK)
- Structured JSON logs
- Correlation IDs per request
- Glyph upload/change audit trail

### Tracing (OpenTelemetry)
- Request flow: Gateway → API → DB → Cache
- Slow query detection
- Cross-service latency breakdown

---

## 6. Backup & Recovery

### Strategy
| Type | Frequency | Retention | Storage |
|------|-----------|-----------|---------|
| DB Snapshot | Hourly | 7 days | S3/GCS |
| DB Backup | Daily | 30 days | S3 + Glacier |
| Glyph JSON Export | Weekly | 90 days | S3 |
| Meta-glyph Archive | On-change | Permanent | S3 + Versioning |

### Recovery RTO/RPO
- **RTO (Recovery Time Objective):** < 1 hour
- **RPO (Recovery Point Objective):** < 5 minutes

---

## 7. Security Hardening

### Input Validation
- Glyph JSON schema validation (serde validator)
- Max payload size: 1MB per glyph
- Rate limiting: 100 req/min per API key

### Network Security
- TLS 1.3 only (Cloudflare)
- API Gateway (Kong) for auth/rate-limiting
- Private DB network (no public access)

### Audit Logging
- All `/glyph/upload` requests logged
- User/IP/timestamp in audit table
- Immutable log storage (WORM)

---

## 8. Scaling Strategy

### Horizontal Scaling
- Stateless API pods (scale to 10 replicas)
- DB read replicas for search queries
- Redis cluster for cache

### Vertical Scaling
- Current: 2 CPU / 2GiB per pod
- Max: 4 CPU / 8GiB per pod (before horizontal)

### Glyph Count Scaling
- 600 glyphs: Current architecture fine
- 6,000 glyphs: Add read replicas, increase cache
- 60,000 glyphs: Sharding by lineage ID

---

## 9. Cost Estimate (Monthly)

| Component | Provider | Cost |
|-----------|----------|------|
| Compute (3 pods) | AWS EKS | $150 |
| PostgreSQL (managed) | AWS RDS | $100 |
| Redis (managed) | AWS ElastiCache | $50 |
| Search (Meilisearch) | Self-hosted | $0 |
| Storage (S3) | AWS S3 | $20 |
| CDN + SSL | Cloudflare | $0 (free tier) |
| **Total** | | **~$320/mo** |

---

## 10. Implementation Phases

### Phase 1: Foundation (Week 1-2)
- [ ] PostgreSQL schema design + migration
- [ ] Replace JSON loader with DB loader
- [ ] Add Redis cache layer
- [ ] Basic auth middleware

### Phase 2: Observability (Week 3)
- [ ] Prometheus metrics export
- [ ] Structured logging
- [ ] Grafana dashboards

### Phase 3: Hardening (Week 4)
- [ ] Rate limiting
- [ ] Input validation
- [ ] Audit logging
- [ ] Backup automation

### Phase 4: Deployment (Week 5)
- [ ] Docker containerization
- [ ] Kubernetes manifests
- [ ] CI/CD pipeline
- [ ] Load testing

---

## Tradeoffs & Questions

### Tradeoffs
1. **PostgreSQL vs SQLite** - PostgreSQL adds complexity but scales better. SQLite simpler for <10k glyphs.
2. **Meilisearch vs Postgres FTS** - Meilisearch better UX, but adds infra. Postgres FTS sufficient for 600 glyphs.
3. **Kubernetes vs Docker Compose** - K8s overkill for single server. Compose simpler for MVP.

### Questions for You
1. **Expected glyph count growth?** (600 → 6,000 or stay at 600?)
2. **Concurrent user load?** (10 users or 10,000?)
3. **Budget constraints?** (Self-hosted vs managed services)
4. **Deployment preference?** (Single server, K8s, or serverless?)
5. **Auth requirements?** (API keys, OAuth, or open?)

---

## Recommendation for MVP

For 600 glyphs with moderate traffic:

```
┌─────────────────────┐
│  Single EC2/Docker  │
│  - Rust API         │
│  - PostgreSQL       │
│  - Redis (optional) │
│  - Daily S3 backup  │
└─────────────────────┘
Cost: ~$50/mo
```

Scale to full infrastructure when:
- Glyph count > 5,000
- Concurrent users > 100
- Upload frequency > 10/day

---

**Ready to proceed with implementation?** I can start with Phase 1 (DB schema + migration) once you confirm the direction.