GLOST Naming Conventions
Comprehensive naming conventions for the GLOST ecosystem following SRP (Single Responsibility Principle) and SSOT (Single Source of Truth).
Core Principles
- Single Responsibility Principle (SRP): Each package does ONE thing
- Single Source of Truth (SSOT): Logic lives in ONE place, never duplicated
- Composition Over Duplication: Import and compose, never copy
- Clear Intent: Package name describes exactly what it does
Package Categories
1. Core Packages (Foundation)
Pattern: glost-[name]
| Package | Responsibility | Example |
|---|---|---|
glost | Core types and node creation | Node factories, type definitions |
@glotblocks/glost-common | Shared utilities and language codes | Language info, validators |
@glotblocks/glost-utils | Text parsing and manipulation | Text utilities, parsers |
@glotblocks/glost-plugins | Extension system | Extension interface, processor |
Naming Rules:
- Simple, descriptive names
- No hyphens for single-word names
- Indicates foundational nature
2. Extension Packages
Pattern: glost-plugins-[type]
| Type | Responsibility | Example |
|---|---|---|
| Translation | Translation generation API | glost-plugins-translation |
| Transcription | Transcription generation API | glost-plugins-transcription |
Naming Rules:
- Always prefixed with
glost-plugins- - Describes the extension category
- Contains extension interface, not implementation
3. Data Source Packages (Composable Layer 1)
Pattern: glost-[lang]-datasource-[source]
| Component | Description | Example |
|---|---|---|
[lang] | ISO 639-1 language code | th, ja, fr |
datasource | Indicates data provider | Always datasource |
[source] | Data source name | lexitron, jmdict, googletrans |
Examples:
glost-th-datasource-lexitron- Thai Lexitron dictionaryglost-ja-datasource-jmdict- Japanese JMDictglost-multi-datasource-googletrans- Multi-language Google Translate
Responsibility: Query data ONLY
- ✅ Fetch from database/API
- ✅ Return raw data structures
- ❌ Process or transform data
- ❌ Apply transcription rules
4. Transcription System Packages (Composable Layer 2)
Pattern: glost-[lang]-transcription-[system]
| Component | Description | Example |
|---|---|---|
[lang] | ISO 639-1 language code | th, ja, zh |
transcription | Indicates transcription system | Always transcription |
[system] | System name | paiboon, rtgs, hepburn, ipa |
Examples:
glost-th-transcription-paiboon- Thai Paiboon+ romanizationglost-th-transcription-rtgs- Thai RTGS romanizationglost-ja-transcription-hepburn- Japanese Hepburn romajiglost-ja-transcription-kunrei- Japanese Kunrei romaji
Responsibility: Apply transcription rules ONLY
- ✅ Transform text using specific rules
- ✅ Work with ANY text input (source-agnostic)
- ❌ Fetch data from databases
- ❌ Handle multiple systems
Special Case - Language-Agnostic:
Pattern: glost-transcription-strategy-[name]
For transcription strategies that work across languages:
glost-transcription-strategy-ipa- IPA transcription (works with any language)
5. Lookup Factory Packages (Composition Layer)
Pattern: glost-[lang]-lookup-[type]-[system]-[source]
| Component | Description | Example |
|---|---|---|
[lang] | Language code | th, ja |
lookup | Indicates composition | Always lookup |
[type] | Data type | transcription, translation |
[system] | System name | paiboon, hepburn |
[source] | Data source | lexitron, jmdict |
Examples:
glost-th-lookup-transcription-paiboon-lexitron- Paiboon+ using Lexitronglost-ja-lookup-transcription-hepburn-jmdict- Hepburn using JMDictglost-th-lookup-translation-googletrans- Translation using Google
Responsibility: Compose components ONLY
- ✅ Import data source package
- ✅ Import transcription system package
- ✅ Wire them together
- ❌ Duplicate any logic
- ❌ Implement transcription rules
- ❌ Implement data queries
6. Plugin Packages (Framework Integration)
Pattern: glost-plugin-[framework]
| Component | Description | Example |
|---|---|---|
plugin | Indicates framework integration | Always plugin |
[framework] | Framework name | inkle, react, vue |
Examples:
glost-plugin-inkle- Inkle/Ink integrationglost-plugin-react- React componentsglost-plugin-vue- Vue components
Extension Naming (Within glost-plugins)
Extensions are categorized by their purpose:
1. Enhancer Extensions
Pattern: [Feature]EnhancerExtension (future - currently just [Feature]Extension)
Purpose: Add display metadata to existing data
Examples:
FrequencyExtension→FrequencyEnhancerExtensionDifficultyExtension→DifficultyEnhancerExtensionPartOfSpeechExtension→PartOfSpeechEnhancerExtensionCulturalNotesExtension→CulturalNotesEnhancerExtension
Responsibility:
- ✅ Transform raw metadata into display-friendly format
- ✅ Add colors, labels, priorities
- ❌ Generate new data
2. Transformer Extensions
Pattern: [Feature]TransformerExtension
Purpose: Modify tree structure
Examples:
ClauseSegmenterExtensionGenderTransformerExtensionNegationTransformerExtension
Responsibility:
- ✅ Modify document tree structure
- ✅ Add/remove/reorganize nodes
- ❌ Just add metadata
3. Generator Extensions
Pattern: [Feature]GeneratorExtension
Purpose: Create new data from external sources
Examples:
TranslationGeneratorExtension(inglost-plugins-translation)TranscriptionGeneratorExtension(inglost-plugins-transcription)
Responsibility:
- ✅ Fetch data from external sources
- ✅ Generate new metadata
- ❌ Just transform existing data
4. Analyzer Extensions
Pattern: [Feature]AnalyzerExtension
Purpose: Complex multi-dependency analysis
Examples:
ReadingScoreAnalyzerExtensionLearnerHintsAnalyzerExtensionClauseAnalysisAnalyzerExtension
Responsibility:
- ✅ Analyze data from multiple sources
- ✅ Compute derived metrics
- ✅ Depend on multiple other extensions
Factory Function Naming
Pattern: create[ExtensionName] ✅ (Already consistent)
Examples:
createFrequencyExtension()createTranscriptionLookup()createFallbackLookup()
File and Directory Structure
Extension Categories
packages/plugins/src/extensions/
├── enhancers/ # Display metadata enhancers (future)
│ ├── frequency.ts
│ ├── difficulty.ts
│ ├── part-of-speech.ts
│ └── cultural-notes.ts
├── transformers/ # Tree structure modifiers (future)
│ ├── clause-segmenter.ts
│ └── gender-transformer.ts
├── generators/ # Moved to separate packages
│ └── (empty)
├── analyzers/ # Complex analyzers (future)
│ ├── reading-score.ts
│ └── learner-hints.ts
└── index.tsData Sources
packages/data-sources/
├── th-datasource-lexitron/
├── ja-datasource-jmdict/
└── multi-datasource-googletrans/Transcription Systems
packages/transcription-systems/
├── th-transcription-paiboon/
├── th-transcription-rtgs/
├── ja-transcription-hepburn/
└── transcription-strategy-ipa/Lookup Factories
packages/lookup-factories/
├── th-lookup-transcription-paiboon-lexitron/
└── ja-lookup-transcription-hepburn-jmdict/Language Codes
Use ISO 639-1 codes (two letters) for all language identifiers:
| Code | Language |
|---|---|
en | English |
th | Thai |
ja | Japanese |
fr | French |
es | Spanish |
zh | Chinese |
ko | Korean |
For multi-language packages, use multi:
glost-multi-datasource-googletrans
Naming Rules Summary
- Use lowercase with hyphens for package names
- Use PascalCase for extension names in code
- Use ISO 639-1 language codes
- Be descriptive - name should explain purpose
- Follow patterns - consistency is key
- Single responsibility - name reflects ONE job
- No abbreviations unless standard (IPA, RTGS)
Quick Reference
| What | Pattern | Example |
|---|---|---|
| Core package | glost-[name] | @glotblocks/glost-common |
| Extension package | glost-plugins-[type] | glost-plugins-transcription |
| Data source | glost-[lang]-datasource-[source] | glost-th-datasource-lexitron |
| Transcription | glost-[lang]-transcription-[system] | glost-th-transcription-paiboon |
| Lookup factory | glost-[lang]-lookup-[type]-[system]-[source] | glost-th-lookup-transcription-paiboon-lexitron |
| Plugin | glost-plugin-[framework] | glost-plugin-react |