GLOST Architecture Summary
Overview
GLOST follows a composable, principle-driven architecture based on SRP (Single Responsibility Principle) and SSOT (Single Source of Truth). The ecosystem is organized into distinct layers, each with clear responsibilities.
Architecture Diagram
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 7: MAIN EXPORT │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ glost │ │
│ │ Main entry point combining core, processor, registry, and presets │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 6: CLI & TOOLS │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ glost-cli Command-line interface for plugin management │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 5: FRONTEND/INTERFACE │
│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │
│ │ glost-react │ │ glost-dialogue │ │
│ │ React components │ │ Dialogue syntax & helpers │ │
│ └──────────────────────────────┘ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 4: PROCESSING INFRASTRUCTURE │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────────────────┐ │
│ │ glost-processor │ │ glost-registry │ │ glost-presets │ │
│ │ .use() API │ │ Discovery │ │ Pre-configured combos │ │
│ └──────────────────┘ └──────────────────┘ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 3: LANGUAGE PACKAGES │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────────────┐ │
│ │ glost-th │ │ glost-ja │ │ glost-ko │ │ glost-en │ │
│ │ Thai │ │ Japanese │ │ Korean │ │ English │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 2: PLUGIN PACKAGES │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌────────────┐ │
│ │ transcription │ │ translation │ │ frequency │ │ difficulty │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌────────────┐ │
│ │ pos │ │ gender │ │ clause-segmenter│ │ inkle │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
↑
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 1: FOUNDATION │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────────────────┐ │
│ │ glost-core │ │ glost-common │ │ glost-utils │ │
│ │ Types & nodes │ │ Language utils │ │ Text manipulation │ │
│ └──────────────────┘ └──────────────────┘ └────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ glost-plugins Core plugin system architecture │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Layer Responsibilities
Layer 1: Foundation
Packages: @glotblocks/glost-core, @glotblocks/glost-common, @glotblocks/glost-utils, @glotblocks/glost-plugins
- Define GLOST node types and interfaces
- Provide tree traversal and manipulation utilities
- Implement plugin system architecture
- Share common language utilities
Layer 2: Plugin Packages
Packages: @glotblocks/glost-transcription, @glotblocks/glost-translation, @glotblocks/glost-frequency, @glotblocks/glost-difficulty, @glotblocks/glost-pos, @glotblocks/glost-gender, @glotblocks/glost-clause-segmenter, @glotblocks/glost-inkle
- Implement specific extension functionality
- Define provider interfaces for data sources
- Return
[generator, enhancer]extension tuples - Handle language-agnostic processing logic
Layer 3: Language Packages
Packages: @glotblocks/glost-th, @glotblocks/glost-ja, @glotblocks/glost-ko, @glotblocks/glost-en
- Compose multiple plugins for a language
- Provide language-specific providers
- Implement language-specific rules (segmentation, transcription)
- Export ready-to-use extensions
Layer 4: Processing Infrastructure
Packages: @glotblocks/glost-processor, @glotblocks/glost-registry, @glotblocks/glost-presets
- Provide unified-style processing API
- Enable plugin discovery and validation
- Detect conflicts between plugins
- Offer pre-configured plugin combinations
Layer 5: Frontend/Interface
Packages: @glotblocks/glost-react, @glotblocks/glost-dialogue
- Render processed GLOST documents
- Provide UI components for common patterns
- Define dialogue/conversation structures
- Handle display-level abstractions
Layer 6: CLI & Tools
Packages: @glotblocks/glost-cli
- Provide command-line interface
- Enable plugin management
- Support discovery and inspection
Layer 7: Main Export
Packages: glost
- Unified entry point for the ecosystem
- Re-exports core, processor, registry, presets
- Simplifies installation and imports
Key Principles
Single Responsibility Principle (SRP)
Each package does one thing well:
| Package | Single Responsibility |
|---|---|
@glotblocks/glost-core | Define types and nodes |
@glotblocks/glost-plugins | Provide extension architecture |
@glotblocks/glost-transcription | Handle pronunciation data |
@glotblocks/glost-processor | Execute plugin pipelines |
@glotblocks/glost-registry | Discover and validate plugins |
Single Source of Truth (SSOT)
Logic lives in one place:
// BAD: Duplicating transcription logic
// in glost-th/transcription.ts
function toPaiboon(word) { /* logic */ }
// in glost-ja/transcription.ts
function toPaiboon(word) { /* same logic */ }
// GOOD: Import from single source
import { createTranscriptionExtension } from '@glotblocks/glost-transcription';Composition Over Duplication
Build complex functionality by composing simple components:
// Language package composes multiple extensions
import { createFrequencyExtension } from '@glotblocks/glost-frequency';
import { createTranscriptionExtension } from '@glotblocks/glost-transcription';
import { createDifficultyExtension } from '@glotblocks/glost-difficulty';
// Compose with language-specific providers
export function createThaiExtensions(providers) {
return [
...createFrequencyExtension({ provider: providers.frequency }),
...createTranscriptionExtension({ provider: providers.transcription }),
...createDifficultyExtension({ provider: providers.difficulty }),
];
}Package Naming Patterns
| Type | Pattern | Example |
|---|---|---|
| Core | glost-{name} | @glotblocks/glost-core, @glotblocks/glost-plugins |
| Plugin | glost-{feature} | @glotblocks/glost-frequency, @glotblocks/glost-pos |
| Language | glost-{lang} | @glotblocks/glost-th, @glotblocks/glost-ja |
| Data Source | glost-{lang}-datasource-{source} | glost-th-datasource-lexitron |
| Transcription | glost-{lang}-transcription-{system} | glost-th-transcription-paiboon |
| Lookup | glost-{lang}-lookup-{type}-{system}-{source} | glost-th-lookup-transcription-paiboon-lexitron |
Mix & Match Examples
Same Data, Different Systems
// Use Lexitron data with different transcription systems
import { createThaiTranscription } from '@glotblocks/glost-th/transcription';
// Paiboon+ system
const paiboonExt = createThaiTranscription({ system: 'paiboon' });
// RTGS system
const rtgsExt = createThaiTranscription({ system: 'rtgs' });
// IPA system
const ipaExt = createThaiTranscription({ system: 'ipa' });Same System, Different Data
// Use same transcription system with different data sources
import { createTranscriptionExtension } from '@glotblocks/glost-transcription';
// With Lexitron data
import { lexitronProvider } from 'glost-th-datasource-lexitron';
const ext1 = createTranscriptionExtension({ provider: lexitronProvider });
// With custom dictionary
import { customProvider } from './my-dictionary';
const ext2 = createTranscriptionExtension({ provider: customProvider });Data Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Input │───▶│ Processor │───▶│ Extensions │───▶│ Output │
│ Document │ │ .use() │ │ Pipeline │ │ Document │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Presets │ │ Providers │
│ (combos) │ │ (data) │
└─────────────┘ └─────────────┘Benefits
| Benefit | Description |
|---|---|
| Maintainability | Fix logic in one place, all packages benefit |
| Testability | Test each component in isolation |
| Reusability | Any system works with any data source |
| Clarity | Package names describe exactly what they do |
| Flexibility | Mix and match components freely |
| No Duplication | Logic is always imported, never copied |
| Tree-shaking | Only import what you need |