Архитектура

Общая схема

TerrAI состоит из трех основных частей:

1. frontend, который отдается через nginx;
2. backend API на FastAPI;
3. PostgreSQL/PostGIS для пользователей и слоев.

Поток запросов:

1. Браузер открывает frontend.
2. nginx обслуживает статические файлы интерфейса.
3. Все запросы /api/* проксируются во backend.
4. Backend обращается к PostgreSQL, OpenRouter и геосервисам OpenStreetMap.
5. Документация проекта /docs/ тоже отдается через тот же frontend nginx.

Frontend

Frontend расположен в каталоге frontend/.

Что делает frontend

• показывает карту;
• отправляет сообщения в чат;
• отправляет скриншоты карты и GeoJSON во backend;
• запускает генерацию PDF;
• управляет авторизацией пользователя;
• отображает и настраивает пользовательские слои.

Технологии и библиотеки frontend

• HTML5
• CSS3
• Vanilla JavaScript с ES modules
• Leaflet для карты
• html2canvas для захвата карты в изображения
• georaster-layer-for-leaflet для отображения GeoTIFF/растра
• geotiff.js для работы с GeoTIFF в браузере
• nginx как web server и reverse proxy для frontend
• MkDocs с темой readthedocs для документации /docs/

Основные frontend-модули

• frontend/main.js — инициализация приложения
• frontend/modules/map.js — карта, базовые слои, координатная панель
• frontend/modules/chat.js — чат и отправка запросов
• frontend/modules/ui.js — боковые панели, PDF, welcome modal
• frontend/modules/auth.js — авторизация
• frontend/modules/layers.js — работа с пользовательскими слоями
• frontend/modules/capture.js — создание скриншотов карты

Backend

Backend расположен в backend/terrai_backend/.

Что делает backend

• принимает chat-запросы;
• генерирует PDF-отчеты;
• обрабатывает auth и user sessions;
• сохраняет и выдает GeoJSON-слои;
• держит контекст чата только в памяти текущей browser/backend-сессии;
• собирает геоконтекст по координатам и объектам OSM;
• отправляет запросы к модели через OpenRouter.

Технологии и библиотеки backend

• Python 3.12
• FastAPI — HTTP API
• Uvicorn — ASGI server
• Pydantic — типы и валидация
• python-multipart — прием multipart/form-data
• psycopg — подключение к PostgreSQL
• psycopg-pool — connection pool
• requests — HTTP-запросы к OpenRouter и геосервисам
• ReportLab — генерация PDF
• python-dotenv — загрузка переменных окружения

Внешние сервисы backend

• OpenRouter — LLM для чата и PDF
• OpenStreetMap Nominatim — reverse/forward geocoding
• OpenStreetMap Overpass — nearby OSM context
• Photon — дополнительный геокодинг, где он еще используется в коде

Основные backend-модули

• server.py — создание FastAPI app и подключение роутеров
• chat_pdf_routes.py — /api/chat, /api/pdf, /api/user/{user_id}
• auth_routes.py — /api/auth/*
• geojson_routes.py — /api/layers, /api/geojson
• openrouter.py — prompt-building и обращения к OpenRouter
• pdf_report.py — построение PDF-отчета
• geodata.py — reverse geocoding и OSM context
• db.py — PostgreSQL pool и SQL helpers
• state.py — usage-limit и in-memory session state
• api_utils.py — общие helpers для request parsing и DB readiness

База данных

Используется PostgreSQL с образом PostGIS.

Что хранится в БД

• users
• auth_sessions
• geojson_documents

Зачем нужен PostGIS

Сейчас в проекте база используется в первую очередь как PostgreSQL-хранилище, но сервис поднимается на PostGIS, чтобы spatial-функции были доступны для дальнейшего развития.

Docker и инфраструктура

Сервисы

• frontend — статический интерфейс и /docs/
• backend — FastAPI API
• postgis — база данных

Инфраструктурные технологии

• Docker
• docker compose
• nginx
• Coolify
• Traefik через labels в compose

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

• проектная документация: /docs/
• Swagger UI backend: /api/docs
• ReDoc backend: /api/redoc
• OpenAPI schema: /api/openapi.json