Architecture & Subsystems
Translato is built with a distributed architecture designed for high availability, real-time collaboration, and seamless external integrations.
1. Redis Data Model
Translato uses Redis for session management, rate limiting, distributed locking, and real-time presence.
Key Patterns
| Key Pattern | TTL | Purpose |
|---|---|---|
session:{sessionId} | 7d | Session data |
user:sessions:{userId}:{sessionId} | 7d | Session membership |
token:access:{tokenId} | 2h | Access token metadata |
token:refresh:{tokenId} | 7d | Refresh token + family |
token:family:{family} | 7d | Token family tracker |
token:family:revoked:{family} | 30d | Revoked family audit |
blacklist:token:{token} | 15m–7d | Blacklisted JWT |
login:attempts:{email} | 15m | Brute-force counter |
2fa:login:{token} | 5m | 2FA challenge proof |
2fa:temp:{userId} | 5m | 2FA setup secret |
email:verify:{token} | 24h | Email verification |
password:reset:{token} | 1h | Password reset |
ratelimit:{key}:{window} | window | Rate limit counter |
ban:{key} | varies | IP/user ban |
rotation:{hash} | 2s | Refresh rotation lock |
audit:{ts}:{random} | 30d | Security audit event |
ws:version:{translationId} | 24h | Optimistic lock version |
ws:presence:{roomId} | 1h | Room presence (hash) |
vcs:oauth:state:{nonce} | 10m | OAuth CSRF state |
vcs:oauth:data:{token} | 5m | OAuth access token |
lock:backup-scheduler | 120s | Scheduler distributed lock |
lock:backup:{projectId} | 5m | Backup operation lock |
lock:vcs-sync:{projectId} | 5m | Webhook sync lock |
webhook:vcs:{projectId} | 60s | Webhook rate limit |
health:check | 10s | Health probe |
2. Integration Subsystems
VCS Integration (GitHub · GitLab · Bitbucket)
Inbound sync (repo → TMS): Webhook → HMAC verify → parse payload → branch filter → acquire Redis lock → fetch files → parse i18n format → diff with existing terms → upsert new, tag removed → log sync
Outbound push (TMS → repo): Load translations → generate file content → create branch → commit files → open PR/MR → log activity
OAuth flow: Authorize → store CSRF state in Redis → redirect to provider → callback → exchange code for token → store token+repos in Redis → redirect frontend with one-time token
Machine Translation (5 providers)
Priority: DeepL → Google → OpenAI → Anthropic → Gemini
- Circuit breaker: 3 failures → open 60s → half-open probe
- Batching: Respects provider limits (30-128 per batch)
- Retry: Failed chunks split in half (max depth 2)
- Timeout: 30s per API call via AbortController
Translation Memory
- Exact match: SHA-256 hash index lookup (instant)
- Fuzzy match: pg_trgm
similarity()with GIN index (requiresCREATE EXTENSION pg_trgm) - Auto-capture: Every translation save → fire-and-forget TM upsert
Backup System
- Distributed locking via Redis
setNX - Filesystem storage (configurable via
BACKUP_STORAGE_DIR) - Checksum verification on restore
- Scheduled: daily/weekly/monthly with retention policies
- Pre-restore safety backup created automatically
Real-Time Collaboration (Socket.IO)
- Redis-backed presence + version counters
- Socket.IO Redis adapter for multi-instance pub/sub
- Optimistic locking with atomic
INCR - All async handlers wrapped in try/catch
3. Packages & SDKs
| Package | Path | Purpose |
|---|---|---|
@translato/database | packages/database | Prisma schema + generated client |
@translato/shared | packages/shared | Shared types, constants, utils |
translato-cli | packages/cli | CLI tool (push/pull/sync/validate/watch) |