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. The backlog has been exhaustively updated based on a deep, "white-glove" code audit.

---

!! 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 has been refactored to handle errors gracefully by using log.Printf instead of log.Fatalf.

---

High Priority

EPIC: Achieve Production-Ready API

• Implement All Unimplemented Resolvers: The GraphQL API is critically incomplete. All of the following panicing resolvers must be implemented.
  • Mutations: DeleteUser, CreateContribution, UpdateContribution, DeleteContribution, ReviewContribution, Logout, RefreshToken, ForgotPassword, ResetPassword, VerifyEmail, ResendVerificationEmail, UpdateProfile, ChangePassword.
  • Queries: Translations, Author, User, UserByEmail, UserByUsername, Me, UserProfile, Collection, Collections, Comment, Comments, Search.
• Refactor API Server Setup: The API server startup in cmd/api/main.go is unnecessarily complex.
  • Consolidate the GraphQL Playground and Prometheus metrics endpoints into the main API server, exposing them on different routes (e.g., /playground, /metrics).

EPIC: Comprehensive Documentation

• Create Full API Documentation: The current API documentation is critically incomplete. We need to document every query, mutation, and type in the GraphQL schema.
  • Update api/README.md to be a comprehensive guide for API consumers.
• Improve Project README.md: The root README.md should be a welcoming and useful entry point for new developers.
  • Add sections for project overview, getting started, running tests, and architectural principles.
• Ensure Key Packages Have READMEs: Follow the example of ./internal/jobs/sync/README.md for other critical components.

EPIC: Foundational Infrastructure

• Establish CI/CD Pipeline: A robust CI/CD pipeline is essential for ensuring code quality and enabling safe deployments.
  • 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.
• Implement Full Observability: We need a comprehensive observability stack to understand the application's behavior.
  • 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.
  • Tracing: Instrument all application services and data layer methods with OpenTelemetry tracing.

EPIC: Core Architectural Refactoring

• Refactor Dependency Injection: The application's DI container in internal/app/app.go violates the Dependency Inversion Principle.
  • Refactor NewApplication to accept repository interfaces (e.g., domain.WorkRepository) instead of the concrete *sql.Repositories.
  • Move the instantiation of platform components (e.g., JWTManager) out of NewApplication and into cmd/api/main.go, passing them in as dependencies.
• Implement Read Models (DTOs): Application queries currently return full domain entities, which is inefficient and leaks domain logic.
  • Refactor application queries (e.g., in internal/app/work/queries.go) to return specialized read models (DTOs) tailored for the API.
• Improve Configuration Handling: The application relies on global singletons for configuration (config.Cfg).
  • Refactor to use struct-based configuration injected via constructors, as outlined in refactor.md.
  • Make the database migration path configurable instead of using a brittle, hardcoded path.
  • Make the metrics server port configurable.

EPIC: Robust Testing Framework

• Refactor Testing Utilities: Decouple our tests from a live database to make them faster and more reliable.
  • Verified that internal/testutil/testutil.go is already database-agnostic.
• Implement Mock Repositories: The test mocks that were incomplete and causing panics have been implemented.
  • Implemented the panic("not implemented") methods in internal/adapters/graphql/like_repo_mock_test.go, internal/adapters/graphql/work_repo_mock_test.go, and internal/testutil/mock_user_repository.go.

---

Medium Priority

EPIC: Complete Core Features

• Implement AnalyzeWork Command: The AnalyzeWork command in internal/app/work/commands.go is currently a stub.
• Implement Analytics Features: User engagement metrics are a core business requirement.
  • Implement like, comment, and bookmark counting.
  • Implement a service to calculate popular translations based on the above metrics.
• Refactor enrich Tool: The cmd/tools/enrich/main.go tool is architecturally misaligned.
  • Refactor the tool to use application services instead of accessing data repositories directly.

EPIC: Further Architectural Improvements

• Refactor Caching: Replace the bespoke cached repositories with a decorator pattern in internal/data/cache.
• Consolidate Duplicated Structs: The duplicated WorkAnalytics and TranslationAnalytics structs have been consolidated into a new internal/domain/analytics package.

---

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.