{"id":34745483,"url":"https://github.com/telemetryflow/telemetryflow-core","last_synced_at":"2026-04-29T23:32:56.009Z","repository":{"id":328785684,"uuid":"1109769126","full_name":"telemetryflow/telemetryflow-core","owner":"telemetryflow","description":"TelemetryFlow Core IAM service (5-Tier RBAC)","archived":false,"fork":false,"pushed_at":"2026-01-12T04:58:29.000Z","size":4056,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T14:00:00.439Z","etag":null,"topics":["cqrs","cqrs-pattern","ddd","ddd-architecture","devopscorner","kiro","kiro-dev","kiro-ide","nestjs","nestjs-backend","observability","opentelemetry","opentelemetry-collector","otel","telemetry","telemetryflow"],"latest_commit_sha":null,"homepage":"https://www.telemetryflow.id","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telemetryflow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T09:00:29.000Z","updated_at":"2026-01-12T04:58:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/telemetryflow/telemetryflow-core","commit_stats":null,"previous_names":["telemetryflow/telemetryflow-core"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/telemetryflow/telemetryflow-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telemetryflow","download_url":"https://codeload.github.com/telemetryflow/telemetryflow-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32448399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"ssl_error","status_checked_at":"2026-04-29T22:10:49.234Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cqrs","cqrs-pattern","ddd","ddd-architecture","devopscorner","kiro","kiro-dev","kiro-ide","nestjs","nestjs-backend","observability","opentelemetry","opentelemetry-collector","otel","telemetry","telemetryflow"],"created_at":"2025-12-25T04:31:09.801Z","updated_at":"2026-04-29T23:32:56.003Z","avatar_url":"https://github.com/telemetryflow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-core-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-core-light.svg\"\u003e\n    \u003cimg src=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-core-light.svg\" alt=\"TelemetryFlow Logo\" width=\"80%\"\u003e\n  \u003c/picture\u003e\n\n  \u003ch3\u003eTelemetryFlow Core IAM service (5-Tier RBAC)\u003c/h3\u003e\n\n[![Version](https://img.shields.io/badge/Version-1.1.4-orange.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![NestJS](https://img.shields.io/badge/NestJS-11.x-E0234E?logo=nestjs)](https://nestjs.com/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-3178C6?logo=typescript)](https://www.typescriptlang.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-4169E1?logo=postgresql)](https://www.postgresql.org/)\n[![ClickHouse](https://img.shields.io/badge/ClickHouse-latest-FFCC00?logo=clickhouse)](https://clickhouse.com/)\n[![DDD](https://img.shields.io/badge/Architecture-DDD%2FCQRS-blueviolet)](src/modules/iam/)\n[![RBAC](https://img.shields.io/badge/Security-5--Tier%20RBAC-red)](README.md#5-tier-rbac-system)\n[![Migrations](https://img.shields.io/badge/migrations-PostgreSQL%208%20%7C%20ClickHouse%204-success.svg)](src/database)\n[![API Coverage](https://img.shields.io/badge/API%20coverage-100%25-brightgreen.svg)](docs/postman/BDD_TESTS.md)\n[![OpenTelemetry](https://img.shields.io/badge/OTLP-100%25%20Compliant-success?logo=opentelemetry)](https://opentelemetry.io/)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat\u0026logo=docker)](https://hub.docker.com/r/telemetryflow/telemetryflow-core)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**TelemetryFlow Core** is a lightweight, production-ready IAM service extracted from the TelemetryFlow Platform. It provides complete identity and access management with a 5-tier RBAC system, multi-tenancy support, and enterprise-grade security features.\n\n## Features\n\n### IAM Module\n- **Multi-tenant architecture**: Tenant → Organization → Workspace hierarchy\n- **User management**: Complete CRUD operations with role-based access\n- **5-Tier RBAC System**: Super Admin, Administrator, Developer, Viewer, Demo\n- **Role-Based Access Control**: Hierarchical roles with 22+ permissions\n- **Group management**: User groups with permission inheritance\n- **Region support**: Multi-region tenant deployment\n- **CQRS pattern**: Separate read/write operations (33 commands, 18 queries)\n- **Domain events**: Event-driven architecture (25+ events)\n\n### Module Standardization System\n- **Quality Gates**: 7 comprehensive standardization gates for all modules\n- **Test Coverage**: 90%+ overall coverage (95% domain layer requirement)\n- **Documentation Generation**: Automated README, API docs, ERD, and DFD generation\n- **Property-Based Testing**: Comprehensive correctness properties with 100 iterations each\n- **Test Structure Validation**: Directory organization and naming convention enforcement\n- **Memory-Optimized Processing**: Efficient file system operations with depth limits\n- **Automated Validation**: Quality enforcement and standardization tooling\n- **DDD Compliance**: Strict Domain-Driven Design architecture patterns\n- **✅ Task 4 Complete**: All documentation and coverage tools working (v1.1.4)\n\n### Architecture\n- **Domain-Driven Design (DDD)**: 8 aggregates, 10 value objects, domain services\n- **CQRS**: Command Query Responsibility Segregation\n- **Clean Architecture**: Domain → Application → Infrastructure → Presentation\n- **Event-Driven**: Domain events for all entity lifecycle changes\n\n### Observability\n- **Swagger/OpenAPI**: Interactive API documentation at `/api`\n- **OpenTelemetry**: Distributed tracing with OTLP export\n- **Winston Logging**: Structured logging with multiple levels\n- **Health Checks**: Built-in health endpoint\n\n### Security\n- **JWT Authentication**: Secure token-based auth\n- **Password Hashing**: Argon2 for secure password storage\n- **Secret Generation**: Cryptographically secure secret generator\n- **Multi-tenancy Isolation**: Organization-level data scoping\n\n## Quick Start\n\n### Prerequisites\n- Node.js 18+\n- pnpm 8+\n- Docker \u0026 Docker Compose\n\n### One-Command Setup\n\n```bash\n# Start all services\ndocker-compose --profile all up -d\n\n# Or start specific profiles\ndocker-compose --profile core up -d                       # Core only\ndocker-compose --profile core --profile monitoring up -d  # Core + Monitoring\n```\n\n### Docker Profiles\n\n**Available profiles:**\n- `core` - Backend, PostgreSQL, ClickHouse\n- `monitoring` - OTEL, Jaeger, Prometheus, Grafana\n- `tools` - Portainer\n- `all` - Everything\n\nSee [docs/DOCKER_SETUP.md](./docs/DOCKER_SETUP.md) for details.\n\n### Manual Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/telemetryflow/telemetryflow-core.git\ncd telemetryflow-core\n\n# Install dependencies\npnpm install\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your configuration\n\n# Generate secrets\npnpm run generate:secrets\n\n# Start infrastructure (PostgreSQL + ClickHouse + OTEL)\ndocker-compose up -d\n\n# Initialize ClickHouse schema\ndocker exec -i telemetryflow_core_clickhouse clickhouse-client --multiquery \u003c config/clickhouse/migrations/001-audit-logs.sql\n\n# Seed database\npnpm run db:seed:iam\n\n# Start development server\npnpm run dev\n```\n\n### Alternative: Bootstrap Script\n\n```bash\nbash scripts/bootstrap.sh --dev\n```\n\n## Architecture\n\n### System Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Client Layer\"\n        Postman[Postman/API Client]\n        Swagger[Swagger UI]\n    end\n\n    subgraph \"Backend Application\"\n        API[NestJS API\u003cbr/\u003e:3000]\n\n        subgraph \"IAM Module - DDD\"\n            Domain[Domain Layer\u003cbr/\u003eAggregates, Entities, VOs]\n            App[Application Layer\u003cbr/\u003eCommands, Queries, Handlers]\n            Infra[Infrastructure Layer\u003cbr/\u003eRepositories, TypeORM]\n            Pres[Presentation Layer\u003cbr/\u003eControllers, DTOs]\n        end\n    end\n\n    subgraph \"Observability Stack\"\n        OTEL[OTEL Collector\u003cbr/\u003e:4318]\n        Jaeger[Jaeger UI\u003cbr/\u003e:16686]\n        Prom[Prometheus\u003cbr/\u003e:9090]\n        Winston[Winston Logger\u003cbr/\u003eFile + OTEL]\n    end\n\n    subgraph \"Data Layer\"\n        PG[(PostgreSQL\u003cbr/\u003eIAM Data)]\n        CH[(ClickHouse\u003cbr/\u003eAudit Logs)]\n    end\n\n    Postman --\u003e API\n    Swagger --\u003e API\n\n    API --\u003e Pres\n    Pres --\u003e App\n    App --\u003e Domain\n    App --\u003e Infra\n    Infra --\u003e PG\n\n    API --\u003e|Traces| OTEL\n    API --\u003e|Metrics| OTEL\n    API --\u003e|Logs| OTEL\n    API --\u003e|Audit| CH\n\n    OTEL --\u003e|Export| Jaeger\n    OTEL --\u003e|Scrape| Prom\n    Winston --\u003e|Export| OTEL\n\n    style API fill:#e1f5ff\n    style Domain fill:#ffe1f5\n    style OTEL fill:#fff4e1\n    style PG fill:#90EE90\n    style CH fill:#FFD700\n```\n\n### DDD Layer Structure\n\n```mermaid\ngraph LR\n    subgraph \"Domain Layer\"\n        AGG[Aggregates\u003cbr/\u003eUser, Role, Permission]\n        ENT[Entities\u003cbr/\u003eMFASettings, Profile]\n        VO[Value Objects\u003cbr/\u003eUserId, Email, RoleId]\n        EVT[Domain Events\u003cbr/\u003eUserCreated, RoleAssigned]\n        SVC[Domain Services\u003cbr/\u003eBusiness Logic]\n    end\n\n    subgraph \"Application Layer\"\n        CMD[Commands\u003cbr/\u003e33 Write Operations]\n        QRY[Queries\u003cbr/\u003e18 Read Operations]\n        HDL[Handlers\u003cbr/\u003e51 Total]\n        DTO[DTOs\u003cbr/\u003eRequest/Response]\n    end\n\n    subgraph \"Infrastructure Layer\"\n        REPO[Repositories\u003cbr/\u003eTypeORM Implementation]\n        MSG[Messaging\u003cbr/\u003eEvent Processors]\n        EXT[External Services\u003cbr/\u003eEmail, SMS]\n    end\n\n    subgraph \"Presentation Layer\"\n        CTRL[Controllers\u003cbr/\u003e9 REST APIs]\n        GRD[Guards\u003cbr/\u003eAuthorization]\n        DEC[Decorators\u003cbr/\u003eCustom Metadata]\n    end\n\n    CTRL --\u003e HDL\n    HDL --\u003e CMD\n    HDL --\u003e QRY\n    CMD --\u003e AGG\n    QRY --\u003e AGG\n    AGG --\u003e EVT\n    HDL --\u003e REPO\n    REPO --\u003e AGG\n    EVT --\u003e MSG\n\n    style AGG fill:#e1f5ff\n    style CMD fill:#ffe1f5\n    style REPO fill:#fff4e1\n    style CTRL fill:#e1ffe1\n```\n\n### Directory Structure\n\n```\nsrc/\n├── main.ts                     # Application entry point\n├── app.module.ts               # Root module\n├── shared/                     # Shared domain primitives\n│   └── domain/\n│       ├── Entity.ts\n│       ├── ValueObject.ts\n│       ├── AggregateRoot.ts\n│       └── DomainEvent.ts\n├── logger/                     # Winston logger module\n├── otel/                       # OpenTelemetry tracing\n├── health/                     # Health check endpoint\n├── database/                   # Database configuration\n│   ├── config/\n│   └── typeorm.config.ts\n└── modules/\n    └── iam/                    # IAM Module (DDD)\n        ├── domain/             # Business logic\n        │   ├── aggregates/       # User, Role, Permission, Tenant, etc.\n        │   ├── entities/         # MFASettings, UserProfile\n        │   ├── value-objects/    # UserId, Email, RoleId, etc.\n        │   ├── events/           # Domain events\n        │   ├── repositories/     # Repository interfaces\n        │   └── services/         # Domain services\n        ├── application/        # Use cases (CQRS)\n        │   ├── commands/         # Write operations (33)\n        │   ├── queries/          # Read operations (18)\n        │   ├── handlers/         # Command/Query handlers (51)\n        │   └── dto/              # Application DTOs\n        ├── infrastructure/     # Technical implementation\n        │   ├── persistence/      # TypeORM repositories \u0026 entities\n        │   └── messaging/        # Event processors\n        └── presentation/       # API layer\n            ├── controllers/      # REST controllers (9)\n            ├── dto/              # Request/Response DTOs\n            ├── guards/           # Authorization guards\n            └── decorators/       # Custom decorators\n\n.kiro/                          # Kiro specifications\n└── specs/                      # Module standardization specs\n    ├── iam-module-standardization/\n    │   ├── requirements.md       # 8 requirements, 80 acceptance criteria\n    │   ├── design.md            # DDD architecture, 8 correctness properties\n    │   └── tasks.md             # 60 implementation tasks\n    ├── audit-module-standardization/\n    ├── auth-module-standardization/\n    └── cache-module-standardization/\n```\n\n## Module Standardization\n\nTelemetryFlow Core follows comprehensive module standardization guidelines to ensure consistency, quality, and maintainability across all modules.\n\n### Standardization Framework\n\nEach module includes detailed specifications in `.kiro/specs/`:\n\n- **IAM Module**: Complete identity and access management standardization\n- **Audit Module**: Audit logging and compliance standardization  \n- **Auth Module**: Authentication and authorization standardization\n- **Cache Module**: Caching and performance standardization\n\n### Quality Gates\n\nAll modules must pass 6 comprehensive quality gates:\n\n| Gate | Requirement | Standard |\n|------|-------------|----------|\n| **Documentation** | Complete documentation with 500+ line README | 100% |\n| **Test Coverage** | Domain: ≥95%, Application: ≥90%, Overall: ≥90% | ≥90% |\n| **File Structure** | DDD compliance with standardized naming | 100% |\n| **Database Patterns** | Standardized migrations, seeds, and naming | 100% |\n| **API Standards** | Swagger, validation, REST conventions | 100% |\n| **Build Quality** | Zero errors in build, lint, and tests | 0 Errors |\n\n### Property-Based Testing\n\nEach module implements 8 correctness properties:\n\n1. **Idempotency** - Operations produce same result when repeated\n2. **Consistency** - Data remains consistent across operations  \n3. **Validation** - All inputs are properly validated\n4. **Authorization** - Access control is enforced\n5. **Persistence** - Data is correctly saved and retrieved\n6. **Event Handling** - Domain events are properly published\n7. **Error Handling** - Errors are handled gracefully\n8. **Performance** - Operations meet performance requirements\n\n### Specification Structure\n\nEach module specification includes:\n\n```\n.kiro/specs/{module}-module-standardization/\n├── requirements.md    # 8 requirements, 80 acceptance criteria (EARS patterns)\n├── design.md         # DDD architecture, components, correctness properties\n└── tasks.md          # 52-60 implementation tasks with checkpoints\n```\n\n### Development Workflow\n\n1. **Review Specifications**: Study requirements, design, and tasks\n2. **Implement Features**: Follow DDD/CQRS patterns\n3. **Validate Quality**: Ensure all quality gates pass\n4. **Property Testing**: Implement correctness properties\n5. **Documentation**: Maintain comprehensive documentation\n\nFor detailed contribution guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md#module-standardization).\n\n## 5-Tier RBAC System\n\n### Role Hierarchy\n\n1. **Super Administrator** (Global)\n   - Platform management across all organizations\n   - All permissions\n\n2. **Administrator** (Organization-scoped)\n   - Full CRUD within organization\n   - Cannot manage platform\n\n3. **Developer** (Organization-scoped)\n   - Create/Read/Update (no delete)\n   - Cannot manage users/roles\n\n4. **Viewer** (Organization-scoped)\n   - Read-only access\n   - Cannot modify resources\n\n5. **Demo** (Demo org only)\n   - Developer access in demo organization\n   - Isolated from production data\n\n### Default Users\n\n| Email | Password | Role | Tier |\n|-------|----------|------|------|\n| superadmin.telemetryflow@telemetryflow.id | SuperAdmin@123456 | Super Administrator | 1 |\n| administrator.telemetryflow@telemetryflow.id | Admin@123456 | Administrator | 2 |\n| developer.telemetryflow@telemetryflow.id | Developer@123456 | Developer | 3 |\n| viewer.telemetryflow@telemetryflow.id | Viewer@123456 | Viewer | 4 |\n| demo.telemetryflow@telemetryflow.id | Demo@123456 | Demo | 5 |\n\n## API Documentation\n\nOnce running, access Swagger UI at: `http://localhost:3000/api`\n\n### Key Endpoints\n\n- **Users**: `/api/users` - User management\n- **Roles**: `/api/roles` - Role management\n- **Permissions**: `/api/permissions` - Permission management\n- **Tenants**: `/api/tenants` - Tenant management\n- **Organizations**: `/api/organizations` - Organization management\n- **Workspaces**: `/api/workspaces` - Workspace management\n- **Groups**: `/api/groups` - Group management\n- **Regions**: `/api/regions` - Region management\n- **Health**: `/health` - Health check\n\n### API Testing\n\n**Postman Collection** (Recommended):\n- Import `docs/postman/TelemetryFlow Core - IAM.postman_collection.json`\n- Import `docs/postman/TelemetryFlow Core - Local.postman_environment.json`\n- 54+ pre-configured requests with default credentials\n- See [docs/postman/README.md](./docs/postman/README.md)\n\n**BDD Automated Testing** (Newman):\n```bash\n# Run all BDD tests\npnpm test:bdd\n\n# Run specific module\npnpm test:bdd:users\npnpm test:bdd:roles\n\n# With detailed output\npnpm test:bdd:verbose\n```\n- 33 BDD test scenarios with Given-When-Then format\n- 100% API coverage\n- HTML and JSON reports\n- See [docs/postman/BDD_TESTS.md](./docs/postman/BDD_TESTS.md)\n\n**Export OpenAPI Spec**:\n```bash\n./scripts/export-swagger-docs.sh\n```\n\n## Makefile Commands (Recommended)\n\nTelemetryFlow Core includes a comprehensive Makefile that simplifies development and CI operations. The Makefile provides standardized commands that work consistently across local development and CI environments.\n\n```bash\n# Quick Start\nmake help                    # Show all available commands\nmake install                 # Install dependencies\nmake dev                     # Start development server\nmake build                   # Build the application\n\n# Development Workflow\nmake start                   # Install + build + start development\nmake reset                   # Clean + install + build (reset environment)\nmake check                   # Quick check (lint + test)\n\n# Code Quality\nmake lint                    # Run ESLint\nmake lint-fix                # Run ESLint with auto-fix\nmake format                  # Alias for lint-fix\n\n# Testing\nmake test                    # Run unit tests\nmake test-coverage           # Run tests with coverage\nmake test-bdd                # Run BDD tests (Newman/Postman)\n\n# Database Operations\nmake db-migrate              # Run database migrations\nmake db-seed                 # Seed database with initial data\nmake db-setup                # Setup database (migrate + seed)\nmake db-cleanup              # Clean up database\n\n# Docker Operations\nmake docker-build            # Build Docker image\nmake docker-run              # Run Docker container locally\nmake docker-stop             # Stop and remove Docker container\nmake up                      # Start all services with Docker Compose\nmake down                    # Stop all services\n\n# CI/CD Pipeline (Used by GitHub Actions)\nmake ci-install              # CI: Install dependencies (frozen lockfile)\nmake ci-validate             # CI: Validate module standardization\nmake ci-lint                 # CI: Run linting\nmake ci-build                # CI: Build application\nmake ci-test                 # CI: Run tests with coverage\nmake ci-security             # CI: Run security audit\nmake ci-pipeline             # CI: Run complete pipeline\n\n# Release Management\nmake release-build           # Build release version\nmake release-docker          # Build and push Docker release\n\n# Utilities\nmake generate-secrets        # Generate JWT and session secrets\nmake bootstrap               # Bootstrap development environment\nmake health                  # Check application health\nmake version                 # Show version information\nmake clean                   # Clean build artifacts and dependencies\n```\n\n### Why Use Makefile?\n\n1. **Consistency**: Same commands work in local development and CI\n2. **Simplicity**: Single command for complex operations\n3. **Documentation**: Self-documenting with `make help`\n4. **Reliability**: Handles error cases and environment setup\n5. **CI Integration**: GitHub Actions use the same Makefile targets\n\n### Example Workflows\n\n```bash\n# New developer setup\nmake install\nmake generate-secrets\nmake db-setup\nmake dev\n\n# Daily development\nmake check                   # Lint + test before committing\nmake reset                   # Reset environment if issues\n\n# CI pipeline (what GitHub Actions runs)\nmake ci-pipeline             # Complete CI validation\n```\n\n## Available Scripts\n\n```bash\n# Development\npnpm dev              # Start with hot reload\npnpm start:debug      # Start with debugger\n\n# Build \u0026 Run\npnpm build            # Build for production\npnpm start            # Start production server\n\n# Database\npnpm db:cleanup              # Clean all databases (PostgreSQL + ClickHouse)\npnpm db:migrate              # Run all migrations (PostgreSQL + ClickHouse)\npnpm db:migrate:postgres     # Run PostgreSQL migrations only\npnpm db:migrate:clickhouse   # Run ClickHouse migrations only\npnpm db:migrate:seed         # Run migrations + seeds (full setup)\npnpm db:seed                 # Seed all data (PostgreSQL + ClickHouse)\npnpm db:seed:postgres        # Seed PostgreSQL only\npnpm db:seed:iam             # Seed IAM data only\npnpm db:seed:clickhouse      # Seed ClickHouse only\npnpm db:init-clickhouse      # Initialize ClickHouse schema\npnpm db:generate-sample      # Generate sample data (50 records)\npnpm db:reset                # Reset database\n\n# Testing\npnpm test                    # Run unit tests\npnpm test:watch              # Watch mode\npnpm test:cov                # Coverage report\npnpm test:bdd                # Run BDD API tests (Newman)\npnpm test:bdd:verbose        # Run BDD tests with detailed output\npnpm test:bdd:users          # Run Users module BDD tests\npnpm test:bdd:roles          # Run Roles module BDD tests\n\n# Security\npnpm generate:secrets        # Generate JWT \u0026 Session secrets\n\n# Code Quality\npnpm lint                    # Lint and fix\n\n# Docker\npnpm docker:up               # Start all containers\npnpm docker:down             # Stop all containers\npnpm docker:logs             # View logs\npnpm docker:clean            # Clean volumes\n\n# Bootstrap\npnpm bootstrap               # Full setup (dependencies, Docker, migrations, seeds)\n\n# API Documentation\n./scripts/export-swagger-docs.sh  # Export OpenAPI spec\n```\n\n## Docker Deployment\n\n### Development\n\n```bash\n# Start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop services\ndocker-compose down\n```\n\n### Production\n\n```bash\n# Build and start\ndocker-compose up -d --build\n\n# Check health\ncurl http://localhost:3000/health\n\n# Access API\ncurl http://localhost:3000/api\n```\n\n### Services\n\n- **PostgreSQL**: 172.151.151.20:5432\n- **ClickHouse**: 172.151.151.40:8123/9000\n- **Backend**: 172.151.151.10:3000\n- **OTEL Collector**: 172.151.151.30:4317/4318\n- **Prometheus**: 172.151.151.50:9090\n\n### OTEL Collector Ports\n\n| Port  | Protocol | Description           |\n| ----- | -------- | --------------------- |\n| 4317  | gRPC     | OTLP gRPC (v1 \u0026 v2)   |\n| 4318  | HTTP     | OTLP HTTP (v1 \u0026 v2)   |\n| 8888  | HTTP     | OTEL Collector metrics|\n| 8889  | HTTP     | Prometheus exporter   |\n| 13133 | HTTP     | Health check          |\n| 55679 | HTTP     | zPages (debugging)    |\n| 1777  | HTTP     | pprof (profiling)     |\n\n### OTLP Endpoints (Dual Ingestion)\n\nThe collector supports both TelemetryFlow (v2) and OTEL Community (v1) endpoints:\n\n**TelemetryFlow Platform (Recommended):**\n\n```text\nPOST http://localhost:4318/v2/traces\nPOST http://localhost:4318/v2/metrics\nPOST http://localhost:4318/v2/logs\n```\n\n**OTEL Community (Backwards Compatible):**\n\n```text\nPOST http://localhost:4318/v1/traces\nPOST http://localhost:4318/v1/metrics\nPOST http://localhost:4318/v1/logs\n```\n\n**gRPC:** `localhost:4317` (both v1 and v2)\n\n## Database Schema\n\n### Core Tables\n- `users` - User accounts\n- `roles` - Role definitions (5-tier RBAC)\n- `permissions` - Permission definitions (22+ permissions)\n- `tenants` - Tenant organizations\n- `organizations` - Business units\n- `workspaces` - Project workspaces\n- `groups` - User groups\n- `regions` - Geographic regions\n\n### Mapping Tables\n- `user_roles` - User-Role assignments\n- `user_permissions` - Direct user-permission assignments\n- `role_permissions` - Role-Permission mappings\n\n## Technology Stack\n\n- **Framework**: NestJS 11.x\n- **Language**: TypeScript 5.9\n- **Database**: PostgreSQL 16\n- **ORM**: TypeORM 0.3\n- **Architecture**: DDD + CQRS\n- **API Documentation**: Swagger/OpenAPI\n- **Logger**: Winston\n- **Observability**: OpenTelemetry (OTEL)\n- **Password Hashing**: Argon2\n- **Package Manager**: pnpm\n\n## Configuration\n\n### Environment Variables\n\n```env\n# Application\nNODE_ENV=development\nPORT=3000\n\n# PostgreSQL\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=5432\nPOSTGRES_DB=telemetryflow_db\nPOSTGRES_USERNAME=postgres\nPOSTGRES_PASSWORD=telemetryflow123\n\n# JWT \u0026 Session\nJWT_SECRET=your-secret-key-min-32-chars\nJWT_EXPIRES_IN=24h\nSESSION_SECRET=your-session-secret-min-32-chars\n\n# Logging\nLOG_LEVEL=info\nLOG_PRETTY_PRINT=true\n\n# OpenTelemetry\nOTEL_ENABLED=true\nOTEL_SERVICE_NAME=telemetryflow-core\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318\n```\n\n## Documentation\n\n### Core Documentation\n- [README.md](./README.md) - Main documentation (this file)\n- [CHANGELOG.md](./CHANGELOG.md) - Version history and changes\n- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines with module standardization\n\n### Module Standardization\n- [Standardization System Documentation](./docs/STANDARDIZATION.md) - Complete standardization framework and implementation guide\n- [Standardization Release Notes](./docs/STANDARDIZATION_RELEASE_NOTES.md) - Version 1.1.4 release information and achievements\n- [IAM Module Standardization](./.kiro/specs/iam-module-standardization/) - Complete IAM module specification\n- [Audit Module Standardization](./.kiro/specs/audit-module-standardization/) - Audit logging standardization\n- [Auth Module Standardization](./.kiro/specs/auth-module-standardization/) - Authentication standardization  \n- [Cache Module Standardization](./.kiro/specs/cache-module-standardization/) - Caching standardization\n\n### Features \u0026 Observability\n- [OBSERVABILITY.md](./docs/OBSERVABILITY.md) - Observability features (OTEL, Prometheus, Swagger)\n- [WINSTON_LOGGER.md](./docs/WINSTON_LOGGER.md) - Winston logger documentation\n- [CLICKHOUSE_LOGGING.md](./docs/CLICKHOUSE_LOGGING.md) - ClickHouse logging (logs, metrics, traces)\n\n### API \u0026 Testing\n- [Postman Collection](./docs/postman/README.md) - API testing with Postman (54+ requests)\n- [BDD Tests](./docs/postman/BDD_TESTS.md) - 33 BDD test scenarios (100% coverage)\n- [BDD Quick Start](./docs/postman/QUICK_START_BDD.md) - Quick reference for automated testing\n- [Swagger Export Script](./scripts/export-swagger-docs.sh) - Export OpenAPI specification\n\n### Modules\n- [IAM Module](./src/modules/iam/README.md) - Identity and Access Management\n\n### Configuration\n- [Configuration Overview](./config/README.md) - All service configurations\n- [PostgreSQL Config](./config/postgresql/README.md) - PostgreSQL settings\n- [ClickHouse Config](./config/clickhouse/README.md) - ClickHouse settings\n- [OTEL Config](./config/otel/README.md) - OpenTelemetry Collector\n- [Prometheus Config](./config/prometheus/README.md) - Metrics collection\n\n### Database\n- [Database README](./src/database/README.md) - Database structure and migrations\n- [PostgreSQL Seeds](./src/database/postgres/seeds/README.md) - Seed data documentation\n- [ClickHouse Seeds](./src/database/clickhouse/seeds/README.md) - ClickHouse seed data\n\n### Maintenance \u0026 Security\n- [SECURITY.md](./SECURITY.md) - Security policy and vulnerability reporting\n- [DEPENDABOT.md](./docs/DEPENDABOT.md) - Automated dependency updates\n- [DEPENDABOT_QUICK_REFERENCE.md](./docs/DEPENDABOT_QUICK_REFERENCE.md) - Quick reference\n- [DEPENDENCY_NOTES.md](./docs/DEPENDENCY_NOTES.md) - Dependency management notes\n\n## Project Statistics\n\n| Metric              | Count    |\n|---------------------|----------|\n| Total Files         | 200+     |\n| Lines of Code       | ~15,000+ |\n| Aggregates          | 8        |\n| Commands            | 33       |\n| Queries             | 18       |\n| Handlers            | 51       |\n| Controllers         | 9        |\n| Entities            | 13       |\n| Domain Events       | 25+      |\n| BDD Test Scenarios  | 33       |\n| API Requests        | 54+      |\n\n## Comparison with **TelemetryFlow Platform**\n\n| Feature | Platform | Core |\n|---------|----------|------|\n| **Modules** | 25+ | 1 (IAM) |\n| **Services** | 15+ | 5 (PostgreSQL, ClickHouse, Backend, OTEL, Prometheus) |\n| **Size** | 150K+ LOC | 15K+ LOC |\n| **Startup** | 10-15s | 2-3s |\n| **Memory** | 500MB-1GB | 100-200MB |\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n**Important:**\n- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines including module standardization\n- Review module specifications in `.kiro/specs/` before working on modules\n- Follow the 6 quality gates for module development\n- Implement property-based testing for comprehensive validation\n- Review [SECURITY.md](./SECURITY.md) for security best practices\n- Follow [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)\n\n### Module Standardization\n\nWhen contributing to modules, ensure compliance with standardization requirements:\n\n- **Quality Gates**: All 6 gates must pass (Documentation, Test Coverage, File Structure, Database Patterns, API Standards, Build Quality)\n- **Test Coverage**: ≥90% overall, ≥95% domain layer\n- **Property Testing**: Implement all 8 correctness properties\n- **Documentation**: Maintain 500+ line README with comprehensive sections\n- **DDD Compliance**: Follow Domain-Driven Design patterns strictly\n\n## Security\n\nSecurity is a top priority. Please review our [Security Policy](./SECURITY.md) for:\n- Reporting vulnerabilities\n- Security best practices\n- Supported versions\n- Contact information\n\n**Report security issues to**: security@devopscorner.id\n\n## License\n\nApache-2.0 License - see [LICENSE](./LICENSE) file for details\n\n## Support\n\n- **Documentation**: [docs/](./docs/)\n- **Issues**: [GitHub Issues](https://github.com/telemetryflow/telemetryflow-core/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/telemetryflow/telemetryflow-core/discussions)\n- **Security**: [SECURITY.md](./SECURITY.md)\n\n## Acknowledgments\n\nExtracted from [TelemetryFlow Platform](https://github.com/telemetryflow/telemetryflow-platform) - Enterprise Telemetry \u0026 Observability Platform.\n\n---\n\n**Built with ❤️ by DevOpsCorner Indonesia** collaboration with [**Kiro**](https://kiro.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-core/lists"}