mirror of https://github.com/SamyRai/tercul-backend.git synced 2025-12-26 22:21:33 +00:00

feat: Implement Bleve migration script and unify CLI (#26 ) (#64 )

* docs: Update TASKS.md and PRODUCTION-TASKS.md to reflect current codebase state (December 2024 audit)

* refactor: Unify all commands into a single Cobra CLI

- Refactor cmd/api/main.go into 'tercul serve' command
- Refactor cmd/worker/main.go into 'tercul worker' command
- Refactor cmd/tools/enrich/main.go into 'tercul enrich' command
- Add 'tercul bleve-migrate' command for Bleve index migration
- Extract common initialization logic into cmd/cli/internal/bootstrap
- Update Dockerfile to build unified CLI
- Update README with new CLI usage

This consolidates all entry points into a single, maintainable CLI structure.

* fix: Fix CodeQL workflow and add comprehensive test coverage

- Fix Go version mismatch by setting up Go before CodeQL init
- Add Go version verification step
- Improve error handling for code scanning upload
- Add comprehensive test suite for CLI commands:
  - Bleve migration tests with in-memory indexes
  - Edge case tests (empty data, large batches, errors)
  - Command-level integration tests
  - Bootstrap initialization tests
- Optimize tests to use in-memory Bleve indexes for speed
- Add test tags for skipping slow tests in short mode
- Update workflow documentation

Test coverage: 18.1% with 806 lines of test code
All tests passing in short mode

* fix: Fix test workflow and Bleve test double-close panic

- Add POSTGRES_USER to PostgreSQL service configuration in test workflow
- Fix TestInitBleveIndex double-close panic by removing defer before explicit close
- Test now passes successfully

Fixes failing Unit Tests workflow in PR #64

2025-11-30 21:54:18 +01:00

3.3 KiB

Raw Permalink Blame History

The Tercul Project

Welcome to Tercul, a modern platform for literary enthusiasts to discover, translate, and discuss works from around the world. This repository contains the backend services, API, and data processing pipelines that power the platform.

Architecture

The Tercul backend is built using a Domain-Driven Design (DDD-lite) approach, emphasizing a clean separation of concerns between domain logic, application services, and infrastructure. Key architectural patterns include:

Command Query Responsibility Segregation (CQRS): Application logic is separated into Commands (for writing data) and Queries (for reading data). This allows for optimized, scalable, and maintainable services.
Clean Architecture: Dependencies flow inwards, with inner layers (domain) having no knowledge of outer layers (infrastructure).
Dependency Injection: Services and repositories are instantiated at the application's entry point (cmd/cli) and injected as dependencies, promoting loose coupling and testability.

For a more detailed explanation of the architectural vision and ongoing refactoring efforts, please see refactor.md.

Getting Started

Follow these instructions to get the development environment up and running on your local machine.

Prerequisites

Go: Version 1.25.0 (as specified in .tool-versions)
Docker & Docker Compose: For running external dependencies like PostgreSQL and Weaviate.
make: For running common development commands.
golangci-lint: For running the linter. Install it with:
```
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
Ensure your Go binary path ($(go env GOPATH)/bin) is in your shell's PATH.

Installation

Clone the repository:
```
git clone <repository-url>
cd tercul
```
Install Go dependencies:
```
go mod tidy
```

Configuration

The application is configured using environment variables. A local docker-compose.yml file is provided to run the necessary services (PostgreSQL, Weaviate, etc.) with default development settings.

The application will automatically connect to these services. For a full list of configurable variables and their default values, see internal/platform/config/config.go.

Running the Application

Start external services:
```
docker-compose up -d
```
Run the API server:
```
go run cmd/cli/main.go serve
```
Or build and run:
```
go build -o bin/tercul ./cmd/cli
./bin/tercul serve
```
The API server will be available at http://localhost:8080. The GraphQL playground can be accessed at http://localhost:8080/playground.

Available Commands

The Tercul CLI provides several commands:

tercul serve - Start the GraphQL API server
tercul worker - Start background job workers
tercul enrich --type <type> --id <id> - Enrich entities with external data
tercul bleve-migrate --index <path> - Migrate translations to Bleve index

Run tercul --help for more information.

Running Tests

To ensure code quality and correctness, run the full suite of linters and tests:

make lint-test

This command executes the same checks that are run in our Continuous Integration (CI) pipeline.

3.3 KiB Raw Permalink Blame History