tercul-backend/TODO.md

TODO List for Tercul Go Application

---

[ ] Performance Improvements

• Implement batching for Weaviate operations (Medium, 2d)

[ ] Security Enhancements

• Add comprehensive input validation for all GraphQL mutations (High, 2d)

[ ] Code Quality & Architecture

• Expand Weaviate client to support all models (Medium, 2d)
• Add code documentation and API docs (Medium, 2d)

[ ] Architecture Refactor (DDD-lite)

• Create skeleton packages: cmd/, internal/platform/, internal/domain/, internal/app/, internal/data/, internal/adapters/graphql/, internal/jobs/
• Move infra to internal/platform/* (config, db, cache, auth, http, log, search)
• Wire DI in cmd/api/main.go and expose an Application facade to adapters
• Unify GraphQL under internal/adapters/graphql and update gqlgen.yml; move schema.graphqls and resolvers
• Resolvers call application services only; add dataloaders per aggregate
• Introduce Unit-of-Work: platform/db.WithTx(ctx, func(ctx) error) and repo factory for *sql.DB / *sql.Tx
• Split write vs read paths for work (commands.go, queries.go); make read models cacheable
• Replace bespoke cached repositories with decorators in internal/data/cache (reads only; deterministic invalidation)
• Restructure models/* into domain aggregates with constructors and invariants
• Adopt migrations tool (goose/atlas/migrate); move SQL to internal/data/migrations; delete migrations.go
• Observability: centralize logging; add Prometheus metrics and OpenTelemetry tracing; request IDs
• Config: replace ad-hoc config with env parsing + validation (e.g., koanf/envconfig); no globals
• Security: move JWT/middleware to internal/platform/auth; add authz policy helpers (e.g., CanEditWork)
• Search: move Weaviate client/schema to internal/platform/search, optional domain interface
• Background jobs: move to cmd/worker and internal/jobs/*; ensure idempotency and lease
• Python ops: move scripts to /ops/migration and /ops/analysis; keep outputs under /ops/migration/outputs/
• Cleanup: delete dead packages (store, duplicate repositories); consolidate to internal/data/sql
• CI: add make lint test test-integration and integration tests with Docker compose

[ ] Testing

• Add unit tests for all models, repositories, and services (High, 3d)
• Add integration tests for GraphQL API and background jobs (High, 3d)
• Add performance benchmarks for critical paths (Medium, 2d)
  • Add benchmarks for text analysis (sequential vs concurrent) and cache hit/miss rates

[ ] Monitoring & Logging

• Add monitoring for background jobs and API endpoints (Medium, 2d)
  • Add metrics for linguistics: analysis duration, cache hit/miss, provider usage

[ ] Next Objective Proposal

• Stabilize non-linguistics tests and interfaces (High, 2d)
  • Fix graph mocks to accept context in service interfaces
  • Update repositories tests (missing TestModel) and align with new repository interfaces
  • Update services tests to pass context and implement missing repo methods in mocks
• Add performance benchmarks and metrics for linguistics (Medium, 2d)
  • Benchmarks for AnalyzeText (provider on/off, concurrency levels)
  • Export metrics and dashboards for analysis duration and cache effectiveness
• Documentation (Medium, 1d)
  • Document NLP provider toggles and defaults in README/config docs
  • Describe SRP/DRY design and extension points for new providers

---

TODO items include context, priority, and estimated effort. Update this list after each milestone.