diff --git a/Makefile b/Makefile
index 633f5cd..99bdbac 100644
--- a/Makefile
+++ b/Makefile
@@ -6,6 +6,8 @@ BASE_BINARY_NAME=datarush
 GW_BINARY_NAME=$(BASE_BINARY_NAME)-gw
 MIGRATE_BINARY_NAME=$(BASE_BINARY_NAME)-migrate
 AUTH_BINARY_NAME=$(BASE_BINARY_NAME)-auth
+COMPETITION_BINARY_NAME=$(BASE_BINARY_NAME)-competition
+TASK_BINARY_NAME=$(BASE_BINARY_NAME)-task
 
 BINARY_DIR=bin
 
@@ -49,10 +51,20 @@ build-auth:
 	$(GOBUILD) -o ./$(BINARY_DIR)/$(AUTH_BINARY_NAME) ./cmd/auth
 	chmod +x ./$(BINARY_DIR)/$(AUTH_BINARY_NAME)
 
-build: build-gw build-migrate build-auth
+build-competition:
+	$(GOBUILD) -o ./$(BINARY_DIR)/$(COMPETITION_BINARY_NAME) ./cmd/competition
+	chmod +x ./$(BINARY_DIR)/$(COMPETITION_BINARY_NAME)
+
+build-task:
+	$(GOBUILD) -o ./$(BINARY_DIR)/$(TASK_BINARY_NAME) ./cmd/task
+	chmod +x ./$(BINARY_DIR)/$(TASK_BINARY_NAME)
+
+build: build-gw build-migrate build-auth build-competition build-task
 
 run:
 	./$(BINARY_DIR)/$(AUTH_BINARY_NAME) &
+	./$(BINARY_DIR)/$(COMPETITION_BINARY_NAME) &
+	./$(BINARY_DIR)/$(TASK_BINARY_NAME) &
 	./$(BINARY_DIR)/$(GW_BINARY_NAME)
 
 migrate: build-migrate
diff --git a/README.md b/README.md
index 001dd76..27d316b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# Datarush
+# DataRush API
 
-Data analysis contest management system
+Data analysis contest management system.
 
 ## Prerequisites
 
@@ -10,52 +10,146 @@ Ensure you have the following installed on your system:
 - protoc (Protocol Buffers compiler)
 - make (latest version recommended)
 
-## Installation
+## Environment Variables
+
+See `infrastructure/<service>/.env.template` for example usage.
+
+## Setup
 
 ### 1. Clone the project
 
 ### 2. Go to the project directory
 
-### 3. Install dependencies
+### 3. Install Dependencies
 
 ```bash
 make i
 ```
 
-### 4. Customize environment
+### 4. Build
 
 ```bash
-cp .env.example .env
+make build-<service name>
 ```
 
-And setup env vars according to your needs.
+### 3. Set Environment Variables
 
-## Configuration
+Create a `.env` file or export variables:
+
+### 4. Run the service
 
 ```bash
-GRPC_PORT=50051              # gRPC server port
-GRPC_ENABLE_REFLECTION=false # whether to enable gRPC reflection or not
-HTTP_HANDLER_ENABLE=false    # whether to enable HTTP gateway or not
-HTTP_PORT=8080               # HTTP gateway port
-LOG_LEVEL=info               # logging severity (debug, info, warn, error)
+./bin/<binary_name>
 ```
 
-## Running
+## API Endpoints
 
-### Build + run
+### 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
-make run
+Authorization: Bearer YOUR_JWT_TOKEN
 ```
 
-### Build
+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
-make build
-```
+# Run tests
+go test ./...
 
-### gRPC code generation
-
-```bash
-make generate
+# Run with coverage
+go test -cover ./...
 ```