tercul-backend/TASKS.md

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)

• 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

• 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
• Refactor API Server Setup: The API server startup has been refactored into cmd/api/server.go with clean separation of concerns.
  • GraphQL Playground and Prometheus metrics endpoints consolidated into main API server at /playground and /metrics.

EPIC: Comprehensive Documentation

• 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.
• 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.
• 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

• Establish CI/CD Pipeline: Basic CI infrastructure exists.
  • 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.
• Implement Basic Observability: Observability infrastructure is in place but needs production hardening.
  • 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.
  • 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.
  • 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

• Refactor Dependency Injection: The composition root has been moved to cmd/api/main.go with proper dependency injection.
  • NewApplication accepts repository interfaces (e.g., domain.WorkRepository) instead of concrete implementations.
  • Platform components (e.g., JWTManager) are instantiated in cmd/api/main.go and passed as dependencies.
• Implement Basic Read Models (DTOs): DTOs are partially implemented.
  • 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.
  • 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.
• Implement Mock Repositories: Mock repositories are fully implemented and functional.
  • All mock repositories in internal/adapters/graphql/*_mock_test.go and internal/testutil/mock_*.go are complete.
  • No panicking mocks found - all methods are properly implemented.

---

Medium Priority

EPIC: Complete Core Features

• Search Implementation: Full-text search is fully implemented with Weaviate.
  • Search service exists in internal/app/search/service.go.
  • Weaviate client wrapper in internal/platform/search/weaviate_wrapper.go.
  • Supports multi-class search (Works, Translations, Authors).
  • 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.
  • 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

• internal/app/work/commands.go: The MergeWork command is fully implemented.
• internal/app/search/service.go: The search service correctly fetches content from the localization service and is fully functional.
• GraphQL API: All resolvers implemented and functional.
• Background Jobs: Sync jobs and linguistic analysis jobs are fully implemented with proper error handling.
• Server Setup: Refactored into cmd/api/server.go with clean middleware chain.
• Basic Observability: Logging, metrics, and tracing infrastructure in place.
• Dependency Injection: Proper DI implemented in cmd/api/main.go.
• API Documentation: Basic documentation exists in api/README.md.