tercul-backend/TASKS.md

Consolidated Tasks for Tercul

This document is the single source of truth for all outstanding development tasks, aligned with the architectural vision in refactor.md.

---

High Priority

Architecture & Refactoring (see refactor.md)

• Implement Full Observability:
  • Centralized Logging: Ensure all services use the structured zerolog logger from internal/platform/log. Add request/user/span IDs to the logging context in the HTTP middleware.
  • Metrics: Add Prometheus metrics for API request latency, error rates, and database query performance. Expose them on the /metrics endpoint.
  • Tracing: Instrument all application services and data layer methods with OpenTelemetry tracing.
• Establish CI/CD Pipeline:
  • CI: Create a Makefile target lint-test that runs golangci-lint and go test ./.... Configure the CI pipeline to run this on every push.
  • CD: Set up automated deployments to a staging environment upon a successful merge to the main branch.
• Refactor Testing Utilities:
  • Decouple from DB: Remove all database connection logic from internal/testutil/testutil.go. Tests should use mock repositories and services, not a live database. This is a key step towards faster, more reliable unit tests.

Features

• Implement Analytics Features:

  • Context: This is required for user engagement insights. The following counts need to be implemented and stored, likely on the Work and Translation models.
  • Implement view counting.
  • Implement like counting.
  • Implement comment counting.
  • Implement bookmark counting.
  • Implement translation counting.
  • Implement a service to calculate popular translations based on the above metrics.
  • Note: This is referenced in the old TODO.md and a TODO comment in internal/jobs/linguistics/work_analysis_service.go.

• Complete Unfinished Implementations:

  • internal/app/work/commands.go: Implement the MergeWork command. This should handle merging duplicate work entries.
  • internal/app/search/service.go: The search service needs to fetch content from the translation service to enrich its search index.
  • cmd/tools/enrich/main.go: This command-line tool is broken. It needs to be investigated, fixed, and documented.

---

Medium Priority

Performance

• Batch Weaviate Operations: Refactor the Weaviate client in internal/platform/search to support batching of create/update operations to improve indexing performance.
• Add Performance Benchmarks: Using Go's built-in benchmarking tools, add benchmarks for critical API queries and commands to detect performance regressions.

Code Quality & Architecture

• Expand Weaviate Client: The client in internal/platform/search should be extended to support indexing all relevant domain models (e.g., Authors, Tags).
• Add Documentation: Add GoDoc comments to all public functions and types in the internal/app and internal/domain packages.
• Refactor Caching: As per refactor.md, replace the current bespoke cached repositories with a decorator pattern in internal/data/cache. This will simplify cache invalidation logic.
• Improve Configuration Handling: Replace the global config object with struct-based configuration loaded from environment variables (e.g., using koanf or envconfig), as outlined in refactor.md.

Monitoring & Logging

• Add Job Monitoring: Add specific monitoring and alerting for background jobs in internal/jobs to track success, failure, and duration.
• Add Linguistics Metrics: Add Prometheus metrics for the linguistics pipeline, including analysis duration, cache hit/miss rates, and third-party API usage.

---

Low Priority

• Refactor Transactional Runner: Refactor the RunTransactional helper in internal/testutil/testutil.go to be more friendly to mock-based testing, likely by allowing a mock DB transaction to be passed in.