From 11331a5c10b58b6d775e652ce5050edfc875ce7a Mon Sep 17 00:00:00 2001
From: ITQ <itq.dev@ya.ru>
Date: Wed, 17 Dec 2025 19:07:00 +0300
Subject: [PATCH] docs: added architecture

---
 ARCHITECTURE.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  8 +++++
 2 files changed, 92 insertions(+)
 create mode 100644 ARCHITECTURE.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..71d1fb2
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,84 @@
+# Architecture and Technologies
+
+## Technologies Used
+
+### PostgreSQL
+
+PostgreSQL was selected as the primary database for its reliability, ACID compliance, and advanced features like JSONB support, which are useful for handling semi-structured data.
+
+### Redis
+
+Redis is used for caching and session management due to its in-memory data store capabilities, which provide extremely low-latency data access.
+
+### MinIO
+
+MinIO serves as the object storage solution, offering S3-compatible APIs. It is lightweight, performant, and ideal for storing large amounts of unstructured data.
+
+### Docker and Docker Compose
+
+Docker is used to containerize the application, ensuring consistency across development and production environments. Docker Compose simplifies the orchestration of multiple services during development.
+
+### Nginx
+
+Nginx is used as a reverse proxy and load balancer to distribute traffic efficiently and ensure high availability.
+
+### Makefile
+
+The Makefile is used to automate common tasks such as building, testing, and running the application, improving developer productivity.
+
+## Services Architecture
+
+### Auth Service
+
+- **Responsibilities**: Handles user authentication and authorization.
+- **Endpoints**: Defined in `auth.proto`.
+
+### User Service
+
+- **Responsibilities**: Manages user profiles and related data.
+- **Endpoints**: Defined in `user.proto`.
+
+### Competition Service
+
+- **Responsibilities**: Manages competitions, including creation, updates, and participant management.
+- **Endpoints**: Defined in `competition.proto`.
+
+### Task Service
+
+- **Responsibilities**: Handles tasks within competitions, including creation and updates.
+- **Endpoints**: Defined in `task.proto`.
+
+### Submission Service
+
+- **Responsibilities**: Handles submissions made by users for tasks.
+- **Endpoints**: Defined in `submission.proto`.
+- **Additional Logic**: Sends messages to Kafka for downstream processing.
+
+### Checker Adapter Service
+
+- **Responsibilities**: Processes new submissions by running checks and validations.
+- **Additional Logic**:
+  - Reads new submission messages from Kafka.
+  - Runs Kubernetes pods to execute the checker logic.
+  - Retrieves results and updates the database.
+
+#### Results Service
+
+- **Responsibilities**: Manages and retrieves results for tasks and competitions.
+- **Endpoints**: Defined in `results.proto`.
+
+#### Review Service
+
+- **Responsibilities**: Handles reviews for submissions.
+- **Endpoints**: Defined in `review.proto`.
+
+#### Achievements Service
+
+- **Responsibilities**: Manages user achievements and badges.
+- **Endpoints**: Defined in `achievements.proto`.
+
+### Communication and Workflow
+
+- **Kafka**: Acts as the message broker for asynchronous communication between the `Submission Service` and the `Checker Adapter Service`.
+- **Kubernetes**: Used by the `Checker Adapter Service` to dynamically run pods for executing submission checks.
+- **PostgreSQL**: Centralized database for storing results and other persistent data.
diff --git a/README.md b/README.md
index 54570d7..aea90c1 100644
--- a/README.md
+++ b/README.md
@@ -51,11 +51,13 @@ Create a `.env` file or export variables:
 ## 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)
@@ -65,6 +67,7 @@ Create a `.env` file or export variables:
 - `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)
@@ -72,26 +75,31 @@ Create a `.env` file or export variables:
 - `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