# 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) - [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. *(Jules' Note: Investigation revealed no panicking code. This task is complete as there is no issue to resolve.)* --- ## High Priority ### EPIC: Achieve Production-Ready API - [x] **Implement All Unimplemented Resolvers:** The GraphQL API is critically incomplete. All of the following `panic`ing resolvers must be implemented. *(Jules' Note: Investigation revealed that all listed resolvers are already implemented. This task is complete.)* - **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. - [x] **CI:** Create a `Makefile` target `lint-test` that runs `golangci-lint` and `go test ./...`. Configure the CI pipeline to run this on every push. *(Jules' Note: The `lint-test` target now exists and passes successfully.)* - [ ] **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. - [ ] Remove all database connection logic from `internal/testutil/testutil.go`. - [x] **Implement Mock Repositories:** The test mocks are incomplete and `panic`. *(Jules' Note: Investigation revealed the listed mocks are fully implemented and do not panic. This task is complete.)* - [x] Implement 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 `WorkAnalytics` and `TranslationAnalytics` structs are defined in two different packages. Consolidate them. --- ## 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.