mirror of
https://github.com/SamyRai/tercul-backend.git
synced 2025-12-27 05:11:34 +00:00
0a27c84771
Key changes include:
- **Architectural Refactoring (CQRS/DTOs):** Refactored the `work` and `translation` application services to use Data Transfer Objects (DTOs) for query responses. This separates the domain layer from the API layer, improving maintainability and performance.
- **Implemented Core Business Logic:** Implemented the `AnalyzeWork` command, which was previously a stub. This command now performs linguistic analysis on works and translations by calling the analytics service.
- **Dependency Injection Improvements:**
- Refactored the configuration loading in `internal/platform/config/config.go` to use a local `viper` instance, removing the reliance on a global singleton.
- Injected the `analytics.Service` into the `work.Service` to support the `AnalyzeWork` command.
- **Comprehensive Documentation:**
- Created a new root `README.md` with a project overview, setup instructions, and architectural principles.
- Added detailed `README.md` files to key packages (`api`, `analytics`, `auth`, `work`, `db`) to document their purpose and usage.
- **Improved Test Coverage:**
- Added new unit tests for the refactored `work` and `translation` query handlers.
- Added a new test suite for the `translation` queries, which were previously untested.
- Added tests for the new `AnalyzeWork` command.
- Fixed numerous compilation errors in the test suites caused by the refactoring.
70 lines
2.8 KiB
Markdown
70 lines
2.8 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/api/main.go`) 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/api/main.go
|
|
```
|
|
The API server will be available at `http://localhost:8080`. The GraphQL playground can be accessed at `http://localhost:8080/playground`.
|
|
|
|
## 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. |