# 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`.
