Abitly Analytics (lake-house)

Метадані

Поле	Значення
Продукт	Abitly.org (data platform)
Тип	Data pipeline / analytics
Статус	🟡 dev (prod ще не задеплоєний)
Власник	@Vladbandurin

Призначення

Lake-house для product-analytics: фронтенд викликає track(event) → подія валідується по JSON-schema → потрапляє в S3 Iceberg → доступна для Athena/dbt/Metabase. Альтернатива/доповнення до GTM (фронт також синхронізує GTM-контейнер через npm run gtm:sync).

Архітектура потоку

Frontend track() ─→ API Gateway ─→ Lambda collector (Ajv validate) ─→ Kinesis Firehose ─→ S3 Iceberg/Parquet
                                                                                                  │
                                                                                                  ▼
                                                                                       Athena ←─ Glue Catalog
                                                                                          │
                                                                                          ▼
                                                                                       dbt models
                                                                                          │
                                                                                          ▼
                                                                                       Metabase

Репозиторій та рантайм


Репо	`abitly-org/abitly-analytics` (`main`)
Стек	TypeScript Lambda (Ajv validation) · Terraform (IaC, state в S3 `abitly-terraform-state`) · dbt models · Metabase
Хостинг — dev	AWS Lambda `abitly-collector-dev` (nodejs20.x, 512 MB) · API Gateway HTTP `abitly-collector-dev` (`5l29l59we6.execute-api.eu-central-1.amazonaws.com`) · Firehose `abitly-events-dev` · S3 `abitly-events-dev` · Athena results `abitly-athena-results-dev`
Metabase	`TODO:` EC2/RDS (з README згадано, але я в AWS прод-екземпляр ще не зустрів)
Прод	❌ не задеплоєний

Залежності

Залежить від: AWS API GW + Lambda + Kinesis Firehose + S3 + Glue + Athena
Від нього залежать: Abitly Web (надсилає події) · TODO: Mini App / API (можуть теж постачати події)

Repository layout

Path	Призначення
`schemas/events.ts`	source-of-truth event taxonomy
`schemas/events.schema.json`	генерована JSON-schema (для Ajv)
`collector/`	TypeScript Lambda (validate/dedup/enrich/forward)
`infra/`	Terraform (API GW, Lambda, Firehose, S3 Iceberg, Glue, Athena, Metabase EC2/RDS)

Env-змінні (Lambda)

TODO: (зчитати з Lambda env у AWS console / SSM /abitly/dev/analytics/).

Ключові команди

npm run schemas:gen     # генерація JSON-schemas з TS-моделі
npm run schemas:check
npm run typecheck
npm run test
# Terraform — у infra/
terraform plan
terraform apply

Логи та моніторинг

Lambda execution logs → CloudWatch /aws/lambda/abitly-collector-dev.
Firehose delivery errors → CloudWatch + S3 error prefix.

Типові проблеми

Події не доходять → перевірити Lambda CloudWatch + Firehose delivery stream.
Schema validation падає → подивитись schemas/events.schema.json vs payload фронту.
Athena returns no rows → перевірити Glue Catalog оновлення з нових Parquet-партіцій.

TODO

Задеплоїти prod-стек.
Узгодити з фронтенд-командою events.ts як npm package замість копіювання.
Документувати dbt-моделі (staging / intermediate / marts).