SpecVital Architecture
🇰🇷 한국어 버전
Overview
SpecVital is a platform for analyzing and visualizing test files in GitHub repositories.
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SpecVital Platform │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────┐ ┌────────────────────────────┐ │ │
│ │ │ web │ │ worker (repository) │ │ │
│ │ │ │ │ │ │ │
│ │ │ API + │ │ ┌──────────┐ ┌─────────┐ │ │ │
│ │ │Dashboard│ │ │ Analyzer │ │Scheduler│ │ │ │
│ │ └────┬────┘ │ └────┬─────┘ └─────────┘ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ ▼ │ │ │
│ │ │ │ ┌────────┐ │ │ │
│ │ │ │ │ core │ (Library) │ │ │
│ │ │ │ └────────┘ │ │ │
│ │ │ └───────┬────────────────────┘ │ │
│ │ │ │ │ │
│ │ └───────────────────┬───────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ PostgreSQL │ │ │
│ │ │ (Data + River Queue) │ │ │
│ │ └──────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘Repositories
core
Role: Tree-sitter based test parser engine
| Item | Description |
|---|---|
| Language | Go |
| Type | Library |
| Consumer | worker |
worker
Role: Analysis workers (analyzer, spec-generator)
| Item | Description |
|---|---|
| Language | Go |
| Dependencies | core, infra (PostgreSQL) |
Data Flow
┌─────────┐ ┌─────────┐
│ User │ │ User │
└────┬────┘ └────▲────┘
│ 1. Request │ 6. View
▼ │
┌─────────────────────────────────────────────────────────────────────────────┐
│ Web Service │
│ │
│ ┌─────────┐ 2. Enqueue 3. Consume ┌───────────┐ │
│ │ web │──────────────────────────────────────────────────▶│ worker │ │
│ │ (API) │ │ (Analyzer)│ │
│ └────┬────┘ └─────┬─────┘ │
│ │ │ │
│ │ 5. Read Results 4. Parse (core) │ │
│ │ │ │
│ │ ┌────────────────────────────┐ │ │
│ └───────────▶│ PostgreSQL │◀────────────────────┘ │
│ │ (Data + River Queue) │ │
│ └────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Flow:
- User requests analysis with GitHub URL
- web enqueues job to River queue (PostgreSQL)
- worker (analyzer) consumes job from River
- worker parses tests via core and stores results
- web reads results from DB
- User views visualized results
Deployment
Platforms
| Service | Platform |
|---|---|
| PostgreSQL | Neon |
| web-backend | Railway |
| web-frontend | Vercel |
| worker-analyzer | Railway |
| worker-scheduler | Railway |
Scalability
| Service | Scalability | Note |
|---|---|---|
| web | Horizontal | Stateless |
| worker (Analyzer) | Horizontal | Stateless, parallel processing |
| worker (Scheduler) | Single instance | Cron jobs |