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

2. **Install dependencies**
   ```bash
   go mod download
   ```

3. **Set up environment**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. **Start development environment**
   ```bash
   docker-compose up -d
   ```

5. **Run migrations**
   ```bash
   go run cmd/migrate/main.go
   ```

6. **Start the server**
   ```bash
   go run cmd/server/main.go
   ```

### Data Migration

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

```bash
# 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

```bash
# Run all tests
go test ./...

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

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

## 🚀 Deployment

### Docker

```bash
# Build image
docker build -t tercul-go .

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

### Docker Compose (Production)

```bash
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](LICENSE) file for details.

## 🆘 Support

For support and questions:

- Create an issue in the repository
- Check the [documentation](docs/)
- Review the [architecture plan](TERCUL_GO_ARCHITECTURE.md)

## 🔄 Migration Status

- [x] Architecture planning
- [x] 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.