# DataRush API

Data analysis contest management system.

## Prerequisites

Ensure you have the following installed on your system:

- Golang (>=1.24)
- protoc (Protocol Buffers compiler)
- make (latest version recommended)

## Environment Variables

See `infrastructure/<service>/.env.template` for example usage.

## Setup with Compose

```bash
docker compose up -d --build --force-recreate --remove-orphans
```

## Setup

### 1. Clone the project

### 2. Go to the project directory

### 3. Install Dependencies

```bash
make i
```

### 4. Build

```bash
make build-<service name>
```

### 3. Set Environment Variables

Create a `.env` file or export variables:

### 4. Run the service

```bash
./bin/<binary_name>
```

## API Endpoints

### Authentication
- `POST /api/v1/sign-up` - Register new user
- `POST /api/v1/sign-in` - Authenticate user
- `GET /api/v1/me` - Get current user profile (requires auth)

### Competitions
- `POST /api/v1/competitions` - Create competition (requires auth)
- `GET /api/v1/competitions` - List competitions (requires auth)
- `GET /api/v1/competitions/{id}` - Get competition details (requires auth)
- `PUT /api/v1/competitions/{id}` - Update competition (requires auth)
- `DELETE /api/v1/competitions/{id}` - Delete competition (requires auth)
- `PATCH /api/v1/competitions/{id}/state` - Change competition state (requires auth)
- `POST /api/v1/competitions/{id}/join` - Join competition (requires auth)

### Tasks
- `POST /api/v1/competitions/{comp_id}/tasks` - Create task (requires auth)
- `GET /api/v1/competitions/{comp_id}/tasks` - List tasks (requires auth)
- `GET /api/v1/competitions/{comp_id}/tasks/{task_id}` - Get task (requires auth)
- `PUT /api/v1/competitions/{comp_id}/tasks/{task_id}` - Update task (requires auth)
- `DELETE /api/v1/competitions/{comp_id}/tasks/{task_id}` - Delete task (requires auth)

### Submissions
- `POST /api/v1/competitions/{comp_id}/tasks/{task_id}/submit` - Submit task with file upload (requires auth)
- `GET /api/v1/competitions/{comp_id}/tasks/{task_id}/history` - Get submission history (requires auth)

### Results
- `GET /api/v1/competitions/{id}/results` - Get competition leaderboard (requires auth)
- `GET /api/v1/competitions/{id}/results/me` - Get my results (requires auth)
- `POST /api/v1/competitions/{id}/results/recalculate` - Recalculate results (requires auth)

### Review (Token-based)
- `GET /api/v1/review/{token}/submissions` - List submissions for review
- `GET /api/v1/review/{token}/submissions/{id}` - Get submission details
- `POST /api/v1/review/{token}/submissions/{id}/evaluate` - Evaluate submission
- `POST /api/v1/review/{token}/submissions/{id}/release` - Release submission

### Achievements
- `GET /api/v1/achievements` - List all achievements (requires auth)
- `GET /api/v1/achievements/{id}` - Get achievement details (requires auth)
- `GET /api/v1/users/{user_id}/achievements` - Get user achievements (requires auth)

### Health Check
- `GET /api/v1/ping` - Health check endpoint

## Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

```bash
Authorization: Bearer YOUR_JWT_TOKEN
```

The gateway validates tokens by calling `AuthService.ValidateToken` and extracts the user ID for subsequent requests.

## Error Handling

The API returns consistent error responses:

```json
{
  "error": "error_type",
  "message": "Human-readable error message"
}
```

HTTP status codes:

- `200` - Success
- `201` - Created
- `204` - No Content
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `409` - Conflict
- `500` - Internal Server Error

## Development

### Gateway Service Structure

- **cmd/**: Entry point with dependency injection
- **config/**: Environment variable configuration
- **domain/**: HTTP request/response models and errors
- **handler/**: HTTP handlers (one per resource)
- **middleware/**: Reusable middleware
- **grpc_client/**: gRPC client wrappers (one per service)
- **storage/**: S3 integration
- **router/**: Route definitions
- **utils/**: Converters and helpers

### Adding New Endpoints

1. Add the endpoint to the OpenAPI spec
2. Update proto files if needed
3. Regenerate proto stubs
4. Add converter functions in `utils/converter.go`
5. Add handler method in appropriate handler file
6. Register route in `router/router.go`

### Testing

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

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