mirror of
https://github.com/SamyRai/tercul-backend.git
synced 2025-12-27 05:11:34 +00:00
be97b587b2
* 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
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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.
|