Przewodnik dla programistów

Ten przewodnik jest przeznaczony dla inżynierów budujących na platformie DataFlow AI Platform. Obejmuje układ monorepo, sposób skonfigurowania lokalnego środowiska deweloperskiego, polecenia budowania i testowania dla każdego komponentu, standardy kodowania wymuszane przez projekt, pętlę deweloperską Docker Compose, debugowanie, proces współtworzenia oraz sposób dodawania nowej usługi backendowej lub funkcji frontendowej.

Architektura w skrócie

DataFlow AI to platforma mikrousługowa z granicami usług zorientowanymi na domeny. API gateway stoi przed sześcioma usługami backendowymi, które współdzielą pojedynczą bazę danych PostgreSQL.

                    +-------------------+
                    |    API Gateway    |
                    |   (Spring Cloud)  |
                    |     port 8080     |
                    +---------+---------+
                              |
        +-------+-------+----+----+-------+-------+
        |       |       |         |       |       |
   +----+--+ +--+---+ +-+------+ +---+--+ +--+--+ +---+----+
   |Metadata| |Engine| |Lineage | |Monitor| | AI  | |Migrate |
   |Service | |      | |Service | |Service| |Copilot| |Engine |
   | :8081  | | :8082| | :8084  | | :8085 | | :8086| | :8087 |
   +---+----+ +--+---+ +---+----+ +---+---+ +--+--+ +---+---+
       |          |         |          |        |         |
       +----------+---------+----------+--------+---------+
                           |
                    +------+------+
                    | PostgreSQL  |
                    | (shared DB) |
                    +-------------+

Odpowiedzialności usług

Komunikacja jest synchroniczna REST między gateway'em a usługami, SSE dla strumieniowania alertów/metryk oraz WebSocket dla statusu pipeline'ów. Kafka do zorientowanego na zdarzenia przyjmowania lineage jest planowana, ale jeszcze nie podłączona.

Układ monorepo

Repozytorium to wielojęzyczne monorepo. Katalogi najwyższego poziomu istotne dla rozwoju to:

polcomtel/
├── backend/
│   ├── platform/            Kotlin services (Gradle multi-project build)
│   │   ├── api-gateway/
│   │   ├── metadata-service/
│   │   ├── pipeline-engine/
│   │   ├── lineage-service/
│   │   ├── monitor-service/
│   │   ├── common/          Shared model + enums
│   │   ├── connector-sdk/   Connector framework + 21 connectors
│   │   ├── pushdown-sql/    SQL dialect / push-down support
│   │   ├── integration-tests/
│   │   ├── settings.gradle.kts
│   │   └── gradlew
│   ├── ai-services/         Python services (Poetry)
│   │   ├── copilot/
│   │   └── migration-engine/
│   ├── cli/                 Go CLI (cmd/, internal/, pkg/)
│   ├── docker/
│   ├── docker-compose.yml
│   └── Makefile
├── frontend/                React + Vite + TypeScript SPA
│   └── src/                 api/, auth/, components/, pages/, hooks/, stores/
├── docs/                    Markdown reference docs + OpenAPI specs
├── docs-ts/                 This documentation site (Next.js + Markdoc)
└── scripts/

Systemy budowania według komponentu

Usługi Kotlina to pojedyncze wieloprojektowe budowanie Gradle zakorzenione w backend/platform/settings.gradle.kts; moduły adresuje się ścieżkami takimi jak :platform:metadata-service.

Konfiguracja lokalnego środowiska deweloperskiego

Wymagania wstępne

Uruchomienie lokalnej infrastruktury

# From backend/ — start PostgreSQL, Keycloak, and Redis
docker-compose up -d

# Verify the stack
docker-compose ps

Stos Compose uruchamia:

Polecenia budowania i testowania dla poszczególnych komponentów

Usługi Kotlina (Gradle)

Uruchom usługę lokalnie zadaniem Spring Boot bootRun:

# Run each service on its port
./gradlew :platform:metadata-service:bootRun    # 8081
./gradlew :platform:pipeline-engine:bootRun     # 8082
./gradlew :platform:lineage-service:bootRun     # 8084
./gradlew :platform:monitor-service:bootRun     # 8085
./gradlew :platform:api-gateway:bootRun         # 8080

Usługi AI w Pythonie (Poetry)

# Copilot service (port 8086)
cd backend/ai-services/copilot
poetry install
poetry run uvicorn copilot.main:app --host 0.0.0.0 --port 8086 --reload

# Migration engine (port 8087)
cd backend/ai-services/migration-engine
poetry install
poetry run uvicorn migration.main:app --host 0.0.0.0 --port 8087 --reload

CLI w Go

cd backend/cli
go build -o dataflow ./cmd

# Verify
./dataflow version
./dataflow login --server http://localhost:8080

Frontend

cd frontend
npm install
npm run dev          # Vite dev server at http://localhost:5173

Walidacja specyfikacji OpenAPI

cd docs/api
npx vitest run __tests__/validate-openapi.test.ts

Lokalna pętla deweloperska Docker Compose

Typowa sesja pętli wewnętrznej łączy skonteneryzowaną infrastrukturę z lokalnie uruchomionymi usługami, dzięki czemu możesz przeładowywać na gorąco (hot-reload) komponent, nad którym pracujesz.

Debugowanie

Specyfikacje OpenAPI

Pełne specyfikacje OpenAPI znajdują się w docs/api/:

Standardy kodowania

Projekt wymusza jeden styl na język. CI uruchamia odpowiedni linter i zawiesza budowanie przy naruszeniu.

Uruchom lintery przed wypchnięciem (push):

./gradlew ktlintCheck            # Kotlin
poetry run ruff check .          # Python (from a service directory)
gofmt -l .                       # Go — lists files needing formatting

Proces współtworzenia

Nazewnictwo gałęzi

feature/<ticket-id>-<short-description>    # New features
fix/<ticket-id>-<short-description>        # Bug fixes
refactor/<description>                     # Refactoring
docs/<description>                          # Documentation only

Przykłady: feature/DF-1234-add-kafka-connector, fix/DF-5678-scheduler-timezone-bug.

Format komunikatu commita

Projekt stosuje Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

feat(engine): add Kafka streaming connector support

Implements KafkaConnector extending NativeConnectorBase with
consumer group management, offset tracking, and exactly-once
semantics via idempotent producer.

Closes: DF-1234

Proces pull request

1. Utwórz gałąź feature z main.
2. Zaimplementuj zmianę razem z jej testami.
3. Upewnij się, że wszystkie testy przechodzą: ./gradlew test.
4. Upewnij się, że lint przechodzi: ./gradlew ktlintCheck (Kotlin), poetry run ruff check . (Python).
5. Wypchnij gałąź i otwórz PR na GitHubie.
6. PR można scalić, gdy ma co najmniej jedno zatwierdzenie od właściciela kodu (code owner), wszystkie kontrole CI przechodzą (budowanie, test, lint, skanowanie bezpieczeństwa) i nie ma konfliktów scalania.
7. Scal do main metodą squash-merge.

Dodawanie nowej usługi backendowej

Nowa usługa Kotlina dołącza do wieloprojektowego budowania Gradle. Kroki wysokiego poziomu:

Usługa AI w Pythonie ma tę samą formę w backend/ai-services/: projekt Poetry z pyproject.toml, aplikacja FastAPI serwowana przez Uvicorn, katalog tests/ testowany przez pytest oraz trasa gateway'a.

Dodawanie nowej funkcji frontendowej

Frontend to jednostronicowa aplikacja React + Vite + TypeScript. Kod źródłowy jest zorganizowany według odpowiedzialności w frontend/src/:

Aby dodać funkcję:

Przegląd poleceń