tercul-backend/docs/architecture/slim_go_tercul_README.md

TERCUL Go Service

A modern, high-performance Go service for the TERCUL cultural exchange platform, designed to replace the existing system while preserving all cultural content and improving performance, maintainability, and scalability.

🚀 Features

• Multi-language Support: Authors, works, and translations in multiple languages
• High Performance: Built with Go 1.24+ for optimal performance
• Modern Architecture: Clean, layered architecture following DDD principles
• Data Preservation: Complete migration from existing SQLite database
• RESTful API: Comprehensive HTTP API with OpenAPI documentation
• GraphQL Support: Flexible query interface for complex data relationships
• Admin Interface: Content management system for administrators
• Search Capabilities: Full-text search and advanced filtering
• Media Management: Efficient handling of images and files
• Security: JWT authentication, role-based access control

📊 Current Data

• Total Records: 1,031,288
• Authors: 4,810
• Works: 52,759
• Work Translations: 53,133
• Countries: 243
• Media Assets: 3,627

🏗️ Architecture

The service follows a clean, layered architecture:

• Presentation Layer: HTTP API, GraphQL, Admin Interface
• Business Layer: Services, Handlers, Middleware
• Data Layer: Repositories, Models, Migrations
• Infrastructure Layer: Database, Cache, Storage

🛠️ Technology Stack

• Language: Go 1.24+
• Framework: Chi router + Echo
• Database: PostgreSQL 16+
• ORM: GORM v3
• Authentication: JWT + OAuth2
• Caching: Redis
• Containerization: Docker + Docker Compose
• Monitoring: Prometheus + Grafana

📁 Project Structure

.
├── cmd/                    # Application entry points
│   ├── migrate/           # Data migration tool
│   ├── seed/              # Data seeding
│   └── server/            # Main HTTP server
├── internal/              # Private application code
│   ├── domain/            # Business entities
│   ├── application/       # Use cases & business logic
│   ├── infrastructure/    # External concerns
│   └── presentation/      # API & interfaces
├── pkg/                   # Public packages
├── scripts/               # Build and deployment
├── docs/                  # Documentation
├── migrations/            # Database migrations
└── docker-compose.yml     # Development environment

🚀 Quick Start

Prerequisites

• Go 1.24+
• Docker & Docker Compose
• PostgreSQL 16+
• Redis 7+

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd tercul-go
   

2. Install dependencies

   go mod download
   

3. Set up environment

   cp .env.example .env
   # Edit .env with your configuration
   

4. Start development environment

   docker-compose up -d
   

5. Run migrations

   go run cmd/migrate/main.go
   

6. Start the server

   go run cmd/server/main.go
   

Data Migration

The service includes a comprehensive migration tool to transfer data from the existing SQLite database:

# Run migration from SQLite dump
go run cmd/migrate/main.go --source=dump_no_owner_2025-08-20_08-07-26.bk

📚 API Documentation

Once the service is running, you can access:

• API Documentation: http://localhost:8080/docs
• Health Check: http://localhost:8080/health
• API Endpoints: http://localhost:8080/api/v1/

🧪 Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test ./internal/domain/author

🚀 Deployment

Docker

# Build image
docker build -t tercul-go .

# Run container
docker run -p 8080:8080 tercul-go

Docker Compose (Production)

docker-compose -f docker-compose.prod.yml up -d

📈 Performance

• Response Time: < 200ms for 95% of requests
• Uptime: 99.9% availability target
• Throughput: Designed to handle 10,000+ concurrent users

🔒 Security

• JWT-based authentication
• Role-based access control
• Input validation and sanitization
• HTTPS enforcement
• Rate limiting
• CORS configuration

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the documentation
• Review the architecture plan

🔄 Migration Status

• Architecture planning
• Project structure setup
• Database schema creation
• Data migration tool
• Core domain models
• API implementation
• Admin interface
• Testing and deployment

📊 Data Quality Issues Addressed

The migration process will automatically fix identified data quality issues:

• Invalid timestamp formats
• UUID format inconsistencies
• HTML content in text fields
• YAML/Ruby format contamination
• Very long content fields

---

Built with ❤️ for preserving cultural heritage through technology.