micsapp Speak Reference Architecture
Overview
Production-ready architecture patterns for Speak language learning integrations.
Prerequisites
- Understanding of layered architecture
- Speak SDK knowledge
- TypeScript project setup
- Testing framework configured
Instructions
- Project Structure
- Layer Architecture
- Key Components
- Data Flow Diagram
- Configuration Management
- Flagship Skills
For full implementation details, load: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)
Output
- Structured project layout
- Client wrapper with caching
- Error boundary implemented
- Health checks configured
- Session management
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Circular dependencies | Wrong layering | Separate concerns by layer |
| Config not loading | Wrong paths | Verify config file locations |
| Type errors | Missing types | Add Speak types |
| Test isolation | Shared state | Use dependency injection |
Examples
Quick Setup Script
# Create reference structure
mkdir -p src/speak/{handlers}
mkdir -p src/lessons src/speech src/progress
mkdir -p src/services/speak src/api/speak src/jobs/speak
mkdir -p tests/{unit,integration,fixtures}/speak
mkdir -p config docs/speak
touch src/speak/{client,config,types,errors}.ts
touch src/lessons/{session,conversation,pronunciation,vocabulary}.ts
touch src/speech/{recognizer,scorer,audio}.ts