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

1. Clone the repository:

   git clone <repository-url>
   cd tercul
   

2. 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

1. Start external services:

   docker-compose up -d
   

2. 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.