A premium, AI-powered flashcard application that helps you master new vocabulary. It integrates with Google Sheets for storage and uses external APIs for definitions, translations, and audio.
- Google Sheets Integration: Your data lives in your own Google Sheet.
- Smart Enrichment: Automatically fetches English definitions, Chinese translations (Traditional), and Pronunciation Audio.
- Real-Time Migration: "Migrate Data" button fixes missing data (like Audio) with a live progress log.
- SRS-Ready: Random recall mode and email reminders.
- Premium UI: Glassmorphism design with responsive animations.
- Go 1.22+: Download Go
- Google Cloud Platform Project: You need a Service Account to access Google Sheets.
- Go to the Google Cloud Console.
- Create a new project (e.g., "Flashcard App").
- Enable the Google Sheets API.
- Create a Service Account:
- Go to "IAM & Admin" > "Service Accounts".
- Click "Create Service Account".
- Grant it "Owner" or "Editor" role (optional, but ensures access).
- Create a Key:
- Click on your new Service Account > "Keys" > "Add Key" > "Create new key" > JSON.
- Download the file and rename it to
credentials.json. - Move it to this project's root folder (
flashcard-app/credentials.json).
⚠️ Security Note: Never commitcredentials.jsonto Git. This project has a.gitignoreto prevent this.
- Create a new Google Sheet at sheets.google.com.
- Share the sheet with your Service Account email (found inside
credentials.json, usually looks like...-compute@developer.gserviceaccount.com). Give it Editor access. - Get the Spreadsheet ID:
- Look at the URL:
https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit... - Copy the long string between
/d/and/edit.
- Look at the URL:
- Create a file named
spreed_id(no extension) in the project root. - Paste the ID inside
spreed_id.
This automatically builds the app and runs it using the ID from your spreed_id file.
make rungo run cmd/main.go -spreadsheet YOUR_ID_HEREOnce running, open your browser to: http://localhost:8080
cmd/main.go: Entry point. Sets up server and dependencies.internal/: Core logic (private to this app).server/: HTTP API handlers (/api/cards,/api/migrate).service/: Business logic (Validation, Enrichment, Migration flow).storage/: Database layer (Google Sheets implementation).enricher/: External API integration (Dictionary API, Translation).email/: Email sending logic.
static/: Frontend files.index.html: Main UI.style.css: Styling.flashcard-bundle.js: Main frontend logic (bundled).
The project includes a robust test suite for the core service logic.
# Run tests
go test -v ./internal/service
# Check code coverage
go test -cover ./internal/service- Context Cancellation: Used
select { case <-ctx.Done(): ... }in long-running migration loops to prevent zombie processes and ensure graceful shutdowns. - Dependency Injection: Decoupled
CardServicefromGoogleSheetsStoreandSMTPSenderusing interfaces, enabling easy testing with mocks. - SSE for Real-Time Logs: Implemented Server-Sent Events to stream migration progress to the frontend without polling.
- Google Sheets as DB: Leveraged Sheets for easy data editing while managing its higher latency and API constraints.
- Concurrency: Preventing race conditions and managing goroutine lifecycles.
- Architecture: Service-Repository pattern for clean separation of concerns.
- Frontend-Backend Sync: Using
EventSourcefor state synchronization during long operations.
- API Rate Limits: Google Sheets API has strict quotas; added delays to avoid hitting limits during bulk updates.
- Frontend State: Managing multi-category filter state required careful logic to handle "OR" filtering correctly.