ClassFlow Draw Service

Microservice for rendering schedules and other images for ClassFlow, written in Go. Provides REST API endpoints that return generated images (binary / base64, depending on your integration).

---

Contents

• Features
• Quick Start
• Prerequisites
• Run with Docker
• Run locally
• API
• GET /api/v2/draw/{object}
• GET /api/v2/themes
• GET /api/v2/themes/{id}
• Configuration
• Monitoring
• Development
• Contributing
• License

---

Features

• RESTful endpoints for image rendering
• Flexible configuration via config.yml
• Docker / Docker Compose support
• Prometheus & Grafana integration (planned)
• Structured logging with pnmd (thanks to TallSmaN)

---

Quick Start

Prerequisites

• Go 1.25
• Docker + Docker Compose

Run with Docker

1. Clone:

git clone https://github.com/Classflow-Devs/draw-service.git
cd draw-service

2. Create config:

cp config.example.yml config.yml

3. Update config.yml with your settings.

4. Start:

docker network create classflow_network
docker compose --profile prod up

If the network already exists, Docker will print an error — it’s fine.

Run locally

cd build
make run-local

---

API

Base path depends on your gateway / reverse proxy. Examples below show raw paths.

GET /api/v2/draw/{object}

Render a specific card/image.

Path params

Parameter	Type	Description	Required
object	string	Card to render (e.g. info_card, schedule)	Yes

Query params

Parameter	Type	Description	Required
theme	string	Theme id/path from static/themes/config.yml (for info_card it may be needed)	No

Example: request body for object=schedule

```json
{
"number": 5,
"name": "Пятница",
"short_name": "ПТ",
"month_with_year": "Декабрь 2024",
"date": "2024-12-13T00:00:00+00:00",
"couple_count": 4,
"start_couple_number": 1,
"couples": [
{
"number": 1,
"type": "Lecture",
"full_type": "Лекция",
"date": "2024-12-13T00:00:00+00:00",
"launch": "",
"discipline": "Математика",
"subgroup": 0,
"teacher": "Капышева Надежда Николаевна",
"short_teacher": "Капышева Н. Н.",
"classroom": "304",
"hull": "12",
"start": "08:30",
"end": "10:00",
"groups": ""
}
]
}
```

Example: request body for object=info_card

```json
{
    "avatar_uri": "https://i.imgur.com/s8CMQIy.jpeg",
    "first_name": "Иван",
    "second_name": "Петров",
    "third_name": "Сергеевич",
    "spark_count": 150,
    "subscription": "ELITE",
    "group_name": "Разработчики"
}
```

Response

• Generated image data (binary or base64 — depends on your integration / gateway).

Tip: Document the exact Accept values your service supports and the response encoding it returns once finalized—for example:

• Accept: image/png → returns raw PNG bytes (Content-Type: image/png)

• Accept: application/json → returns JSON with a data field (e.g., { "data": "..." })

• Accept: text/plain → returns the image as a Base64-encoded string (Content-Type: text/plain; charset=utf-8)

---

GET /api/v2/themes

Return available themes for a role.

Query params

Parameter	Type	Description	Required
role	string	Filters themes by role. Default: public	No

Response example

```json
{
"themes": [
{
"display_name": "🧡 Оранжевая",
"id": "colors.orange",
"preview_url": "",
"description": "Теплая классическая визуальная тема в мягких оттенках оранжевого.\n...",
"role": "public"
},
{
"display_name": "💜 Фиолетовая",
"id": "colors.purple",
"preview_url": "",
"description": "Спокойная классическая визуальная тема в оттенках фиолетового.\n...",
"role": "public"
}
]
}
```

---

GET /api/v2/themes/{id}

Return a single theme by id.

Path params

Parameter	Type	Description	Required
id	string	Theme id (e.g. colors.orange)	Yes

Response example

```json
{
"theme": {
"display_name": "🧡 Оранжевая",
"id": "colors.orange",
"preview_url": "",
"description": "Теплая классическая визуальная тема...\n",
"role": "public"
}
}
```

---

Configuration

Service is configured via config.yml.

Typical options you’ll see there:

• Server host/port
• Notification service address (for “active couple” / current slot logic)
• Theme/static paths (if applicable)

Keep config.example.yml always up to date with new config keys.

---

Monitoring

• Prometheus metrics endpoint: GET /api/v2/metrics (planned)

---

Development

Run tests

go test ./tests/...

Useful make targets

cd build
make run-local

---

Contributing

1. Fork the repository
2. Create a new branch: feature/my-change
3. Commit changes
4. Push branch
5. Open a Pull Request

---

License

MIT — see LICENSE.