---

Описание проекта

ATLAS — это backend-first Telegram-продукт для управления повседневной жизнью через одного бота.

Идея проекта — собрать в одном Telegram-интерфейсе сценарии, которые обычно размазаны по разным приложениям: планирование, чек-ины, привычки, фокус, тренировки, восстановление, питание и недельную рефлексию.

Пользователь общается с одним ботом, а backend маршрутизирует запросы к специализированным агентам ATLAS.

ATLAS не является фронтенд-приложением, лендингом или веб-кабинетом. Основной фокус этого репозитория — backend, Telegram-интеграция, хранение данных, сценарии общения и агентная архитектура.

---

Core Scope

flowchart TD
    User["Пользователь"] --> Telegram["Telegram Bot"]

    Telegram --> Adapter["Telegram Adapter"]
    Adapter --> Core["ATLAS Core"]

    Core --> Routing["Маршрутизация сценариев"]
    Core --> State["Состояние диалогов"]
    Core --> Storage["PostgreSQL / Flyway"]
    Core --> Agents["Агенты ATLAS"]
    Core --> LLM["Опциональный LLM Provider"]

    Agents --> Planner["Планирование"]
    Agents --> Coach["Тренировки"]
    Agents --> Reflection["Рефлексия"]

    LLM --> Fallback["Deterministic fallback"]

Loading

ATLAS Core отвечает за:

• приём и обработку Telegram-событий;
• маршрутизацию пользовательских запросов;
• управление состоянием диалогов;
• работу с сохранёнными пользовательскими данными;
• подключение специализированных агентов;
• безопасный fallback, если LLM отключён или недоступен.

---

Архитектура

ATLAS развивается как модульный монолит с явными bounded contexts, application use cases, ports-and-adapters границами, внутренними событиями и архитектурными тестами.

Проект намеренно не дробится на микросервисы раньше времени, но сохраняет понятный путь к будущему выделению Telegram gateway, life tracking, LLM agents, memory и reporting.

ATLAS is built as a modular monolith with explicit bounded contexts, application use cases, ports-and-adapters boundaries, internal events and CI-enforced architecture rules.

The project intentionally avoids premature microservices while keeping clear future extraction paths for Telegram gateway, life tracking, LLM agents, memory and reporting.

Документация:

• Архитектура RU
• Architecture EN
• ADR RU
• ADR EN

---

Агенты

В базовой модели ATLAS использует несколько специализированных агентов.

Агент	Зона ответственности
ATLAS Core	оркестрация, маршрутизация, состояние диалогов и связь между компонентами
ATLAS Planner	планирование дня, недели, приоритетов и следующих действий
ATLAS Coach	тренировки, нагрузка, дисциплина и поддержка физической активности

Архитектура не ограничивается только этими агентами. В дальнейшем можно добавлять собственных агентов под конкретные сценарии: питание, сон, восстановление, финансы, обучение, работу, проекты или любые другие life-ops направления.

---

Быстрый старт

Рекомендуемый локальный запуск:

git clone https://github.com/ATLAS-lifeops/ATLAS.git
cd ATLAS
make start

Команда make start:

• запускает Docker Compose;
• ждёт готовности backend;
• открывает страницу первичной настройки.

Страница настройки:

http://localhost:8080/setup

Проверка состояния приложения:

http://localhost:8080/actuator/health

Запуск тестов:

mvn test

Полезные команды для локальной разработки:

make up
make down
make logs
make restart
make status
make clean

---

Локальная настройка

ATLAS поддерживает два основных локальных сценария запуска.

1. Setup Mode

Подходит для первого запуска без заранее подготовленного .env.

make start

После запуска открой:

http://localhost:8080/setup

Дальше:

1. вставь Telegram Bot Token;
2. выбери локальный polling-режим;
3. сохрани настройки;
4. напиши /start боту в Telegram.

2. Preconfigured Local Bot Mode

Подходит для запуска с заранее заполненным .env.

cp .env.example .env

Добавь локально Telegram token:

ATLAS_TELEGRAM_BOT_TOKEN=<telegram-bot-token>

Затем запусти проект:

make start

Если ATLAS_TELEGRAM_BOT_TOKEN задан, приложение проверит токен через Telegram getMe, сохранит runtime-настройки и запустит локальный polling-режим.

Не добавляй реальные секреты в репозиторий.

---

Telegram-режимы

ATLAS поддерживает два режима работы с Telegram.

Режим	Назначение
POLLING	простой локальный режим, в котором приложение само читает обновления через Telegram getUpdates
WEBHOOK	production-режим, в котором Telegram отправляет события на публичный backend endpoint

Локально чаще всего используется POLLING.

В production рекомендуется использовать WEBHOOK.

---

LLM Support

По умолчанию система может работать без LLM-провайдера и использовать deterministic responses. Это позволяет запускать проект локально, тестировать Telegram UX и проверять основные сценарии без внешнего AI API.

ATLAS предусматривает подключение OpenAI-compatible provider для будущего развития LLM-powered agents.

Документация по настройке:

• LLM setup RU
• LLM setup EN

Если LLM отключён, настроен неполно или провайдер недоступен, ATLAS должен продолжать работать через безопасные fallback-ответы.

---

Production Telegram Launch

Production-запуск рассчитан на webhook-режим.

1. Минимальные переменные окружения

ATLAS_TELEGRAM_ENABLED=true
ATLAS_TELEGRAM_BOT_TOKEN=<telegram-bot-token>
ATLAS_TELEGRAM_BOT_USERNAME=<telegram-bot-username>
ATLAS_TELEGRAM_MODE=webhook
ATLAS_TELEGRAM_WEBHOOK_PATH=/telegram/webhook
ATLAS_TELEGRAM_WEBHOOK_SECRET=<random-webhook-secret>
ATLAS_PUBLIC_BASE_URL=https://<public-domain>
ATLAS_TELEGRAM_REGISTER_WEBHOOK_ON_STARTUP=true

2. Health endpoint

GET /actuator/health

3. Telegram webhook endpoint

POST /telegram/webhook

4. Production checklist

Перед production-запуском проверь:

• backend доступен по публичному HTTPS-домену;
• ATLAS_PUBLIC_BASE_URL указывает на production-домен;
• webhook secret задан и не хранится в репозитории;
• Telegram token не попадает в логи и публичные ответы;
• health endpoint возвращает корректный статус;
• webhook endpoint принимает Telegram updates;
• включена регистрация webhook при старте или webhook зарегистрирован вручную.

---

Roadmap

Roadmap отражает развитие проекта по ключевым релизам. Подробная история изменений находится в changelog-документации.

Версия	Фокус	Статус
v0.2.0	Docker, Docker Compose, PostgreSQL, базовый health check и конфигурация окружения	Завершено
v0.3.0	первая реальная Telegram-интеграция, webhook receiver и command routing	Завершено
v0.3.1	стабилизация Telegram-интеграции, безопасная обработка обновлений и длинных ответов	Завершено
v0.3.2	очистка backend-only репозитория, удаление устаревших frontend-артефактов	Завершено
v0.3.3	production webhook mode, webhook secret validation и production-документация	Завершено
v0.4.0	PostgreSQL/Flyway persistence, runtime settings, setup page, polling mode и сохранение Telegram-активности	Завершено
v0.5.0	onboarding, life profile, conversation states, check-ins, habits, evening reflection и weekly report	Завершено
v0.5.1	button-first Telegram UX, выбор языка RU/EN, inline keyboards, main menu, settings/profile panels	Завершено
v0.5.2	local launch polish: make start, auto-open setup, safe .env, preconfigured local bot mode	Завершено
v0.5.3	Telegram UX stabilization: back/menu buttons, flow continuation, settings/profile polish, docs reorganization	Завершено
v0.5.4	modular monolith foundation, use-case boundaries, internal events, architecture docs and rules	Завершено
v0.6.0	LLM abstraction, OpenAI-compatible provider, deterministic fallback, базовая AI-инфраструктура	В работе / следующий этап
v0.6.1	развитие LLM-powered agents и более умная маршрутизация пользовательских сценариев	Запланировано

---

Документация

Основная документация разделена на русскую и английскую версии.

• Русская документация
• English documentation

Полезные разделы:

• Архитектура RU
• Architecture EN
• Локальный запуск
• Local launch
• Telegram UX RU
• Telegram UX EN
• LLM setup RU
• LLM setup EN
• История изменений RU
• Changelog EN

---

---