# Consolidated Tasks for Tercul (Production Readiness) This document is the single source of truth for all outstanding development tasks, aligned with the architectural vision in `refactor.md`. Last updated: December 2024 --- ## !! CRITICAL !! ### Stabilize Core Logic (Prevent Panics) - [x] **Fix Background Job Panic:** The background job queue in `internal/jobs/sync/queue.go` can panic on error. This must be refactored to handle errors gracefully. *(Status: Complete - Investigation revealed no panicking code. All background jobs handle errors gracefully.)* --- ## High Priority ### EPIC: Achieve Production-Ready API - [x] **Implement All Unimplemented Resolvers:** The GraphQL API is complete. All resolvers are implemented and functional. - **Mutations:** `DeleteUser`, `CreateContribution`, `UpdateContribution`, `DeleteContribution`, `ReviewContribution`, `Logout`, `RefreshToken`, `ForgotPassword`, `ResetPassword`, `VerifyEmail`, `ResendVerificationEmail`, `UpdateProfile`, `ChangePassword` - ✅ All implemented - **Queries:** `Translations`, `Author`, `User`, `UserByEmail`, `UserByUsername`, `Me`, `UserProfile`, `Collection`, `Collections`, `Comment`, `Comments`, `Search` - ✅ All implemented - [x] **Refactor API Server Setup:** The API server startup has been refactored into `cmd/api/server.go` with clean separation of concerns. - [x] GraphQL Playground and Prometheus metrics endpoints consolidated into main API server at `/playground` and `/metrics`. ### EPIC: Comprehensive Documentation - [x] **Create Full API Documentation:** Basic API documentation exists in `api/README.md` with all queries, mutations, and types documented. - [ ] Enhance `api/README.md` with more detailed examples, error responses, and usage patterns. - [ ] Add GraphQL schema descriptions to improve auto-generated documentation. - [x] **Improve Project `README.md`:** The root `README.md` has been updated with project overview, getting started guide, and architectural principles. - [ ] Add more detailed development workflow documentation. - [ ] Add troubleshooting section for common issues. - [x] **Ensure Key Packages Have READMEs:** `internal/jobs/sync/README.md` exists as a good example. - [ ] Add READMEs for other critical packages (`internal/app/*`, `internal/platform/*`). ### EPIC: Foundational Infrastructure - [x] **Establish CI/CD Pipeline:** Basic CI infrastructure exists. - [x] **CI:** `Makefile` target `lint-test` exists and runs `golangci-lint` and `go test ./...` successfully. - [ ] **CD:** Set up automated deployments to a staging environment upon a successful merge to the main branch. - [ ] **GitHub Actions:** Create `.github/workflows/ci.yml` for automated testing and linting. - [x] **Implement Basic Observability:** Observability infrastructure is in place but needs production hardening. - [x] **Centralized Logging:** Structured `zerolog` logger exists in `internal/observability/logger.go`. Request IDs and span IDs are added to logging context via middleware. - [ ] **Logging Enhancements:** Add user ID to authenticated request logs. Implement log sampling for high-volume endpoints. - [x] **Metrics:** Basic Prometheus metrics exist for HTTP requests and database queries (`internal/observability/metrics.go`). - [ ] **Metrics Enhancements:** Add GraphQL resolver metrics, business metrics (works created, searches performed), and cache hit/miss metrics. - [x] **Tracing:** OpenTelemetry tracing is implemented with basic instrumentation. - [ ] **Tracing Enhancements:** Replace stdout exporter with OTLP exporter for production. Add database query tracing via GORM callbacks. Instrument all GraphQL resolvers with spans. ### EPIC: Core Architectural Refactoring - [x] **Refactor Dependency Injection:** The composition root has been moved to `cmd/api/main.go` with proper dependency injection. - [x] `NewApplication` accepts repository interfaces (e.g., `domain.WorkRepository`) instead of concrete implementations. - [x] Platform components (e.g., `JWTManager`) are instantiated in `cmd/api/main.go` and passed as dependencies. - [x] **Implement Basic Read Models (DTOs):** DTOs are partially implemented. - [x] `WorkDTO` exists in `internal/app/work/dto.go` (minimal implementation). - [ ] **Enhance DTOs:** Expand DTOs to include all fields needed for list vs detail views. Create `WorkListDTO` and `WorkDetailDTO` with optimized fields. - [ ] **Extend to Other Aggregates:** Create DTOs for `Translation`, `Author`, `User`, etc. - [ ] **Optimize Queries:** Refactor queries to use optimized SQL with proper joins to avoid N+1 problems. - [ ] **Improve Configuration Handling:** The application still uses global singletons for configuration (`config.Cfg`). - [ ] Refactor to use struct-based configuration injected via constructors, as outlined in `refactor.md`. - [x] Database migration path is configurable via `MIGRATION_PATH` environment variable. - [ ] Make metrics server port configurable (currently hardcoded in server setup). - [ ] Add configuration validation on startup. ### EPIC: Robust Testing Framework - [ ] **Refactor Testing Utilities:** Tests currently use live database connections. - [ ] Refactor `internal/testutil/testutil.go` to use testcontainers for isolated test environments. - [ ] Add parallel test execution support. - [ ] Create reusable test fixtures and builders. - [x] **Implement Mock Repositories:** Mock repositories are fully implemented and functional. - [x] All mock repositories in `internal/adapters/graphql/*_mock_test.go` and `internal/testutil/mock_*.go` are complete. - [x] No panicking mocks found - all methods are properly implemented. --- ## Medium Priority ### EPIC: Complete Core Features - [x] **Search Implementation:** Full-text search is fully implemented with Weaviate. - [x] Search service exists in `internal/app/search/service.go`. - [x] Weaviate client wrapper in `internal/platform/search/weaviate_wrapper.go`. - [x] Supports multi-class search (Works, Translations, Authors). - [x] Supports filtering by language, tags, dates, authors. - [ ] **Enhancements:** Add incremental indexing on create/update operations. Add search result caching. - [ ] **Implement Analytics Features:** Basic analytics exist but needs completion. - [x] Analytics service exists in `internal/app/analytics/`. - [ ] **Complete Metrics:** Implement like, comment, and bookmark counting (currently TODOs in `internal/jobs/linguistics/work_analysis_service.go`). - [ ] Implement service to calculate popular translations based on engagement metrics. - [ ] **Refactor `enrich` Tool:** The `cmd/tools/enrich/main.go` tool may need architectural alignment. - [ ] Review and refactor to use application services instead of accessing data repositories directly (if applicable). ### EPIC: Further Architectural Improvements - [ ] **Implement Repository Caching:** Caching exists for linguistics but not for repositories. - [ ] Implement decorator pattern for repository caching in `internal/data/cache`. - [ ] Create `CachedWorkRepository`, `CachedAuthorRepository`, `CachedTranslationRepository` decorators. - [ ] Implement cache-aside pattern with automatic invalidation on writes. - [ ] Add cache metrics (hit/miss rates). - [ ] **Consolidate Duplicated Structs:** Review and consolidate any duplicated analytics structs. - [ ] Check for `WorkAnalytics` and `TranslationAnalytics` duplication across packages. --- ## Low Priority ### EPIC: Code Quality & Documentation - [ ] **Add GoDoc Comments:** Document all public functions and types. - [ ] **Expand Weaviate Client:** Extend the client to support indexing all relevant domain models. - [ ] **Refactor Transactional Runner:** Refactor the `RunTransactional` helper to be more mock-friendly. --- ## Completed - [x] `internal/app/work/commands.go`: The `MergeWork` command is fully implemented. - [x] `internal/app/search/service.go`: The search service correctly fetches content from the localization service and is fully functional. - [x] GraphQL API: All resolvers implemented and functional. - [x] Background Jobs: Sync jobs and linguistic analysis jobs are fully implemented with proper error handling. - [x] Server Setup: Refactored into `cmd/api/server.go` with clean middleware chain. - [x] Basic Observability: Logging, metrics, and tracing infrastructure in place. - [x] Dependency Injection: Proper DI implemented in `cmd/api/main.go`. - [x] API Documentation: Basic documentation exists in `api/README.md`.