Skip to Content
DocumentationArchitecture

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:

PackageSingle Responsibility
@glotblocks/glost-coreDefine types and nodes
@glotblocks/glost-pluginsProvide extension architecture
@glotblocks/glost-transcriptionHandle pronunciation data
@glotblocks/glost-processorExecute plugin pipelines
@glotblocks/glost-registryDiscover 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

TypePatternExample
Coreglost-{name}@glotblocks/glost-core, @glotblocks/glost-plugins
Pluginglost-{feature}@glotblocks/glost-frequency, @glotblocks/glost-pos
Languageglost-{lang}@glotblocks/glost-th, @glotblocks/glost-ja
Data Sourceglost-{lang}-datasource-{source}glost-th-datasource-lexitron
Transcriptionglost-{lang}-transcription-{system}glost-th-transcription-paiboon
Lookupglost-{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

BenefitDescription
MaintainabilityFix logic in one place, all packages benefit
TestabilityTest each component in isolation
ReusabilityAny system works with any data source
ClarityPackage names describe exactly what they do
FlexibilityMix and match components freely
No DuplicationLogic is always imported, never copied
Tree-shakingOnly import what you need
Last updated on