# 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:
  ```bash
  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:**
    ```bash
    git clone <repository-url>
    cd tercul
    ```

2.  **Install Go dependencies:**
    ```bash
    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:**
    ```bash
    docker-compose up -d
    ```

2.  **Run the API server:**
    ```bash
    go run cmd/cli/main.go serve
    ```
    Or build and run:
    ```bash
    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:

```bash
make lint-test
```

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