1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**totalrecall** - Bulgarian Anki Flashcard Generator
A Go CLI tool that generates Anki flashcard materials from Bulgarian words:
- Generates audio pronunciation using OpenAI TTS
- Generates images using OpenAI DALL-E
- Creates Anki-compatible output files
## Important: Task Tracking
**Always check TODO.md for the current implementation status and pending tasks.** The TODO.md file contains a comprehensive breakdown of all features and their completion status.
## Build and Development Commands
### Available Tasks (via Taskfile)
```bash
# Build the binary
task
# or
task default
# Run the application
task run
# Run tests
task test
# Install to Go bin directory
task install
```
### Common Development Commands
```bash
# Build for current platform
go build -o totalrecall ./cmd/totalrecall
# Run without building
go run ./cmd/totalrecall "ябълка"
# Run tests with coverage
go test -v -cover ./...
# Check for race conditions
go test -race ./...
# Format code
go fmt ./...
# Lint code (requires golangci-lint)
golangci-lint run
```
## Architecture Overview
### Package Structure
```
totalrecall/
├── cmd/totalrecall/ # CLI entry point
├── internal/ # Private packages
│ ├── audio/ # Audio generation (OpenAI TTS)
│ ├── image/ # Image generation functionality
│ ├── anki/ # Anki format generation
│ ├── config/ # Configuration management
│ └── version.go # Version information
├── assets/ # Static assets and configuration
│ ├── icons/ # Application icons
│ ├── config.yaml.example # Example configuration
│ ├── totalrecall.desktop # Desktop entry file
│ └── install-icon.sh # Icon installation script
```
### Key Design Decisions
1. **OpenAI TTS**: High-quality, natural-sounding Bulgarian pronunciation
2. **Image generation**: Uses OpenAI DALL-E for AI-generated images
3. **Configuration via YAML**: User-friendly configuration with viper
4. **Cobra for CLI**: Industry-standard CLI framework
### External Dependencies
- **OpenAI API Key**: Required for both audio generation and image creation
## Testing Approach
1. Unit tests mock API calls
2. Integration tests use real services when available
3. Test with common Bulgarian words: ябълка, котка, куче, хляб
## Common Issues and Solutions
### Package Declaration Error
If you see an error about `package main`, ensure `cmd/totalrecall/main.go` has:
```go
package main // NOT package bulg
```
## Development Workflow
1. Check TODO.md for next tasks
2. Create feature branch
3. Implement with tests
4. Update documentation
5. Run full test suite
6. Submit for review
## Bulgarian Language Notes
- Input should be in Cyrillic script
- Common test words: ябълка (apple), котка (cat), куче (dog)
- OpenAI voices: nova, alloy, echo, shimmer (work well for Bulgarian)
## Code Guidelines
- Whenever updating code, also update the comments in the code to reflect the reality and the reasoning.
- When a function reaches 50 lines of code or more, try to refactor it into several functions of about 30 lines each. In case of a go project, when main.go becomes too large, move code into the ./internal package.
## File Organization
- Configuration examples, desktop files, and installation scripts should be placed in the `assets/` directory
- Icons and images go in `assets/icons/`
- Keep the root directory clean by moving non-essential files to appropriate subdirectories
|
