(July 2025 - Present)
TuranBilgi is a modern, API-first, multi-client business platform designed to support complex domain workflows alongside high-performance real-time communication. The platform follows a distributed microservices architecture with event-driven coordination, enabling independent scaling, fault isolation, and long-term extensibility across backend services and client applications.
TuranBilgi is designed as a unified backend system serving multiple client applications through a shared API layer. All business logic, authentication, authorization, and real-time capabilities are centralized within the platform and exposed through a shared API layer. This ensures consistent behavior across all consuming clients while allowing internal services to evolve independently. It is designed around long-term platform sustainability rather than short-term feature delivery. Its architecture emphasizes:
All platform capabilities are exposed through well-defined REST and GraphQL APIs. This guarantees that web, mobile, desktop, and third-party integrations operate on a shared and stable contract, while preserving internal service autonomy.
TuranBilgi adopts an event-driven architecture for internal coordination, background processing, and state propagation between services. Asynchronous messaging (Kafka & RabbitMQ) enables loose coupling between services, improves resilience, and supports scalable background processing.
This clear separation of communication patterns ensures resilience, observability, and long-term maintainability.
The platform is composed of multiple domain-focused microservices, each owning its data model and execution context. This prevents cascading failures and ensures that issues in one domain (such as discussion, chat, or real-time notification) do not compromise core business functionality.
All services are designed to be stateless and container-friendly, enabling independent horizontal scaling of Core, Interaction, Payment, Real-Time, and AI components or microservices based on workload characteristics.
Each service uses the storage technology best suited to its domain:
This approach optimizes performance while preserving clear data ownership and service autonomy and maintainability.
WebSocket-based presence, notifications, and messaging are designed to remain consistent and responsive under concurrent load, supporting real-time collaboration and communication use cases at scale.
Authentication, business logic, communication, payments, and intelligence are treated as independently bounded domains. This enables long-term evolution of the platform without cross-service entanglement or architectural rewrites.
TuranBilgi is intentionally structured for incremental evolution. New services, additional client applications (web, mobile, desktop), and external integrations can be introduced without architectural rewrites or disrupting existing functionality, with preserving platform stability while enabling continuous growth.
TuranBilgi platform consists of several domain microservices, each focused on a specific area of platform functionality while communicating and coordinating through events or synchronous API calls.
The Core Business microservice is implemented using Node.js (Express.js with TypeScript) and exposes both REST and GraphQL APIs. It serves as the primary orchestration and transactional domain service of the platform, coordinating long-running business workflows, enforcing business rules, and managing the lifecycle of core business entities.
This microservice does not replace domain ownership of other services, but instead acts as the central workflow coordinator and external-integration boundary, ensuring that domain services remain decoupled from infrastructure and third-party concerns.
The Core Business microservice supports a collaborative and moderated workflow where users and administrators interact to create, refine, and finalize ideas, projects, contracts, invoices, and support tickets. It manages multi-step, stateful workflows that span multiple domains and user roles:
In addition to business workflows, the Core Business microservice is responsible for:
The Core Business microservice acts as the central gateway for external asynchronous integrations, while preserving a fully event-driven internal architecture.
All domain microservices emit internal domain events through Kafka using their own outbox patterns.
The Core Business microservice is the sole consumer responsible for translating selected domain events into external side effects, such as:
External integrations are intentionally not handled directly by domain services. Instead:
This design prevents infrastructure concerns from leaking into domain services and ensures consistent handling of external systems.
Primary relational database for business-critical, transactional data (users, admins, ideas, projects, applications, contracts, invoices, support tickets).
Document-oriented, write-optimized, and schema-flexible storage used for outbox persistence, event projection support, and supplementary non-relational data.
Caching, distributed coordination, rate-limiting, and performance optimization.
Internal event streaming backbone for inter-service communication, domain events, and audit propagation.
Asynchronous job processing and external integration queuing, used exclusively for side-effect-driven workflows such as email and SMS delivery.
This approach ensures:
To support structured communication, decision-making, and accountability across all business domains, TuranBilgi includes a dedicated Interaction & Discussion microservice. This service implements a unified, reusable interaction model that enables threaded discussions, contextual replies, moderation workflows, and historical traceability for all major business entities.
Rather than embedding isolated comment systems within individual services, TuranBilgi centralizes all collaborative interactions into a shared domain layer, ensuring consistency, scalability, and governance.
The microservice is implemented using NestJS with TypeScript and exposes both REST and GraphQL interfaces. It operates in close coordination with the Core Business microservice through an event-driven Saga-based architecture.
All major platform entities require structured communication and collaborative workflows:
| Entity | Purpose | Discussion Support |
|---|---|---|
| Idea | Brainstorming | Yes |
| Support Ticket | Problem Solving | Yes |
| Project | Coordination | Yes |
| Project App | Requirements Analysis | Yes |
| Contract | Negotiation | Yes |
| Invoice | Billing Questions | Yes |
| Payment | Dispute Resolution | Yes |
These entities share common interaction requirements:
This unified design is referred to internally as the Shared Interaction Model.
The Interaction & Discussion microservice is implemented using NestJS and provides both REST and GraphQL APIs. It operates independently from the Core Business API and focuses exclusively on collaborative workflows. Key responsibilities include:
The service exposes:
This dual-interface strategy enables frontend teams to select the most appropriate interaction model for each client application.
The interaction subsystem is optimized for high-volume, write-heavy collaboration workloads.
All discussions are linked to business entities through a generic entity reference model, enabling flexible cross-domain associations without schema coupling.
The service integrates with the platform’s event-driven infrastructure.
This ensures synchronization between business workflows and interaction state.
The Interaction & Discussion microservice provides:
It functions as the platform’s unified collaboration and discourse layer.
To support secure, scalable, and regulation-compliant financial operations, TuranBilgi includes a dedicated Payment, Billing & Financial Processing microservice. This microservice handles payment intents, billing workflows, PSP integrations, settlement reconciliation, and fraud prevention, isolating financial execution from core business logic and maintaining strong transactional boundaries.
Rather than embedding payment logic directly within the Core Business API, TuranBilgi isolates all monetary processing into a specialized domain service. This separation ensures strong security boundaries, regulatory compliance, independent scalability, and fault isolation for all financial operations.
The microservice is implemented using NestJS with TypeScript and exposes REST APIs for transactional workflows and webhook integrations. It operates in close coordination with the Core Business microservice through an event-driven Saga-based architecture.
The Payment microservice functions as the platform’s financial execution and settlement layer. It is responsible for:
All financial state transitions are managed locally and synchronized with other services via Kafka events, avoiding cross-service database coupling.
The microservice manages the full lifecycle of invoice payments, including:
All payment operations are executed within database transactions and coordinated through the outbox pattern to guarantee consistency.
A dedicated adapter layer abstracts third-party payment providers and normalizes their APIs into a unified internal interface. This layer supports:
This design enables seamless migration or multi-provider support without impacting upstream business logic.
The microservice exposes secure webhook endpoints to receive asynchronous confirmations and settlement notifications from PSPs. Key responsibilities include:
Webhook processing pipelines are isolated from public APIs to prevent external interference with transactional state.
The Payment microservice participates in distributed business workflows using event-driven Saga choreography. It emits domain events such as:
These events are published via the MongoDB Outbox and Kafka pipeline and consumed by the Core Business and Real-Time services to update invoice states, trigger notifications, and generate audit records. No direct database access between services is permitted, preserving domain isolation.
To ensure long-term financial accuracy and regulatory compliance, the microservice includes automated reconciliation pipelines. These processes support:
This subsystem provides resilience against message loss, provider outages, and partial failures.
The payment service incorporates security and compliance controls, including:
Sensitive card data is never stored within platform databases and is handled exclusively by certified PSPs.
The Payment microservice exposes specialized APIs optimized for transactional reliability.
GraphQL is intentionally excluded from payment execution paths to reduce complexity and ensure deterministic transactional behavior.
The microservice maintains its own isolated relational database optimized for financial workloads.
All monetary records are immutable and append-only, ensuring auditability and traceability.
The microservice is tightly integrated with TuranBilgi’s event-driven infrastructure.
This bidirectional integration enables consistent financial synchronization across distributed domains.
To guarantee financial correctness in a distributed environment, the Payment microservice employs:
These mechanisms ensure consistency without requiring distributed transactions.
The Payment, Billing & Financial Processing microservice provides:
It functions as the platform’s dedicated financial execution and settlement authority while remaining loosely coupled to core business workflows.
A dedicated NestJS and Socket.IO–based microservice is responsible for managing all real-time communication, notification delivery, and centralized audit projections across the distributed platform, ensuring responsive client experiences and operational traceability. The service maintains persistent WebSocket connections and exposes REST and GraphQL APIs to support scalable, low-latency client interactions.
Rather than acting as a centralized event authority, this microservice operates as a specialized consumer and processor within a federated, domain-driven event architecture. Each domain service owns its own event production and outbox mechanisms, while this service focuses on real-time delivery, notification orchestration, and audit aggregation.
The microservice provides a full-featured, managed chat and collaboration subsystem supporting both private and room-based communication.
Through REST and GraphQL interfaces, administrators can:
These management capabilities enable controlled, enterprise-grade collaboration environments.
The chat subsystem supports:
All messaging operations are synchronized across distributed gateways using Kafka and Redis to ensure consistency and fault tolerance.
The platform implements a flexible, event-driven notification system supporting both manual and automated workflows. This microservice acts as the primary notification orchestration and delivery engine, consuming domain events emitted by distributed services and transforming them into user-facing notifications.
A. Manual (Admin-Driven)
Administrators can:
B. System-Generated (Event-Driven)
Distributed domain services emit notification-related events via their own MongoDB Outbox and Kafka publishing
mechanisms for business events such as:
These events are published to Kafka by the originating services and consumed by the notification processors for delivery.
The notification subsystem supports:
This enables accurate notification lifecycle management and user engagement tracking.
This microservice serves as the centralized audit projection and compliance authority for the Turan Bilgi platform.
All domain microservices emit standardized audit events as part of their own transactional workflows using the MongoDB Outbox pattern. These events are reliably published to Kafka through service-local outbox processors, ensuring atomicity, durability, and failure isolation without cross-service coupling.
The Realtime microservice acts as the sole consumer and persistence owner of audit events. It consumes audit-related Kafka topics, validates and enriches incoming events, and persists them into an immutable, append-only audit log store.
This design enforces clear ownership boundaries: domain services are responsible only for emitting audit intent, while audit persistence, retention, and compliance guarantees are centralized. The approach preserves domain autonomy, avoids distributed transactions, and enables scalable, fault-tolerant audit processing through event-driven architecture.
To support multi-instance deployments and horizontal scaling:
This infrastructure enables independent scaling of producers and consumers while maintaining platform-wide consistency, or ensuring consistent behavior across clusters.
This microservice is designed to scale independently from core business and interaction microservices and provides:
It functions as the platform’s real-time delivery and compliance projection layer, rather than as a centralized event authority.
To support advanced intelligence, automation, and knowledge-driven features, TuranBilgi includes an optional AI Microservice that extends the platform’s capabilities into natural language understanding, semantic search, content summarization, and assisted workflows.
The AI microservice is developed using Python and built on the FastAPI framework, enabling high-performance asynchronous processing and scalable API-driven intelligence services. This service operates as an independent extension layer within the microservice architecture, allowing AI capabilities to evolve separately from the core business services.
The AI microservice is designed as a loosely coupled, language-agnostic intelligence layer that consumes business events (such as idea creation, discussion updates, and support ticket changes) and produces knowledge artifacts that enhance user experience and platform insight. It does not replace existing services but augments them with machine-assisted intelligence.
By isolating AI workloads into a dedicated Python-based service, TuranBilgi ensures:
This architecture enables TuranBilgi to progressively introduce intelligent features without compromising the stability or modularity of the core platform.
The AI microservice provides:
The AI microservice operates independently from the other microservices but integrates through the platform’s event infrastructure:
This separation maintains microservice boundaries, avoids direct coupling to the database store of other microservices, and enables independent scaling of AI workloads.
Adding the AI microservice to the platform enables:
While the core platform handles transactional and collaboration workloads, the AI microservice is designed for extensibility into:
This aligns with TuranBilgi’s long-term extensibility goals while preserving clear service boundaries.
TuranBilgi adopts a shared JWT-based authentication model across all microservices to ensure consistent and secure identity propagation throughout the system.
The Core Business service acts as the primary identity authority, issuing signed JWT access tokens after successful authentication. Client applications include these tokens in subsequent requests to other microservices, which independently validate the token signature and claims without requiring centralized session storage.
This approach provides:
JWT expiration policies and claim validation mechanisms enforce time-bound access while preserving scalability and performance.
This model balances strong security guarantees with operational simplicity, avoiding the need for centralized session management or complex gateway-level token orchestration.
TuranBilgi follows a structured, multi-layered testing strategy designed to ensure reliability, security, and long-term scalability across its distributed microservice architecture.
Testing is implemented using modern, ecosystem-appropriate frameworks (such as Jest, Vitest, SuperTest, MSW, and language-native testing tools) depending on service requirements. This layered testing strategy supports safe refactoring, reduces regression risk, and ensures consistent behavior in a distributed environment.
All services follow clearly defined validation layers to ensure correctness, resilience, and predictable system behavior. The testing strategy includes:
The AI microservice is tested using:
Testing environments are fully isolated from production and are provisioned using containerized infrastructure. They include:
Integration tests run against real, isolated service dependencies to accurately simulate production interactions without impacting live systems. Unit tests mock messaging clients, while integration tests validate real message flows against isolated broker instances. This ensures realistic validation of event-driven communication without impacting production systems. This approach ensures deterministic, reproducible results across local development and continuous integration (CI) environments.
Each microservice runs automated tests in the CI pipeline on:
Pipelines enforce:
No service can be deployed unless it passes all automated quality gates.
Security is integrated into the testing lifecycle through:
This ensures resilience against common attack vectors and misconfigurations.
This testing strategy was chosen to:
By aligning testing tools with each technology stack (NestJS, Express/Fastify, FastAPI), TuranBilgi achieves both architectural clarity and operational stability. This approach balances developer velocity with strict quality controls, enabling rapid innovation without compromising system stability.
The entire ecosystem is containerized under the TuranDocker project. This includes the Core Business, Interaction, Payment, and Real-Time microservices, PostgreSQL, MongoDB, Redis, Apache Kafka, RabbitMQ, reverse proxies (Nginx), and all the observability & monitoring tools. This setup enables fast, repeatable deployments on any Linux VPS while providing a strong foundation for future orchestration with Kubernetes or other container platforms, while remaining fully operational with Docker Compose or Docker Swarm.
To ensure data durability and disaster recovery, TuranBilgi implements automated backup pipelines for critical data stores:
These mechanisms guarantee that production data remains protected, restorable, and resilient against operational faults or disasters.
TuranBilgi adopts a comprehensive observability and monitoring strategy to provide deep visibility into system behavior,
performance, and reliability across its distributed landscape. Observability goes beyond basic monitoring by correlating
metrics, logs, and error events to enable rapid diagnosis and root cause analysis in complex deployments.
The observability platform includes:
A containerized Prometheus stack collects metrics from services, databases, brokers, and runtime resources (CPU, memory, request latencies, consumer lag, queue depths, etc.). Alerts are configured for critical thresholds (e.g., error rates, slowdowns, resource saturation) to notify stakeholders automatically.
Grafana is used to visualize time-series metrics and create operational dashboards that display key indicators such as API performance, Kafka consumer health, RabbitMQ queue statistics, and WebSocket connection trends, turning raw telemetry into actionable insight.
Sentry captures exceptions, stack traces, and contextual request metadata from all services, enabling quick identification of issues in production and correlating failures with release versions and service flows.
OpenTelemetry-based tracing can be integrated to visualize cross-service request flows and event-driven interactions, providing deeper insight into distributed transactions.
For centralized log analysis and search, a logging stack (e.g., Loki with Promtail or a full ELK stack) ingests and indexes logs from all containers. Correlating logs with metrics and traces helps answer not only what is happening, but why it is happening — critical for distributed systems and complex workflows.
Together, these components provide a unified observability surface that enhances operational confidence, reduces time to resolution, and supports continuous performance optimization as the platform evolves.
TuranBilgi is intentionally designed with orchestration portability in mind. While the platform currently operates efficiently using Docker Compose or Docker Swarm, its container boundaries, stateless service design, externalized configuration, and volume management patterns ensure a smooth migration path to Kubernetes when scaling requirements justify it.
Ideal for:
Benefits:
At this stage, Kubernetes would add unnecessary operational weight.
Suitable when:
Swarm provides:
However, Swarm remains simpler than Kubernetes and is often sufficient for medium-scale production workloads.
Migration to Kubernetes becomes justified when TuranBilgi experiences one or more of the following:
Kubernetes introduces production-grade orchestration capabilities such as:
Ensure all services:
Convert Docker Compose services into:
Migrate infrastructure components:
Introduce:
Gradually transition traffic from VPS deployment to Kubernetes cluster.
Because TuranBilgi already enforces clean container boundaries, this migration would be structural rather than architectural. Infrastructure evolution does not require service redesign, preserving long-term architectural stability.
API Gateways (e.g., Kong, KrakenD, Nginx Plus, Ambassador) provide centralized request routing, authentication, rate limiting, caching, and observability at the edge.
For TuranBilgi, an API Gateway is not necessary in early stages because:
When an API Gateway Becomes Justified:
Adding a gateway is incremental and should occur only when operational complexity or external exposure grows beyond what direct service calls can safely and efficiently manage.
Service meshes provide:
However, they introduce:
For TuranBilgi, a service mesh is not required when:
In early and mid-stage deployments, adding Istio or Consul Connect would be architectural overengineering.
For TuranBilgi, a service mesh may become beneficial if:
At that stage:
TuranBilgi’s architecture is intentionally modular and container-native, ensuring that orchestration upgrades can occur without redesigning core services.
TuranBilgi prioritizes:
This approach ensures that infrastructure evolves in response to real operational needs rather than theoretical scalability assumptions.
While TuranBilgi currently uses a microservice architecture, future extensions may incorporate Serverless and Micro-Frontend patterns:
Serverless can be used for event handlers, AI inference, webhook integrations, and other bursty workloads without requiring always-on infrastructure.
Micro-Frontends enable independent UI modules (e.g., Chat, Notifications, AI Assist), allowing teams to develop, release, and scale UI components autonomously.
These patterns are not required at MVP, but become meaningful and beneficial as the platform grows, teams scale, and feature sets become more independent.
TuranBilgi is a multi-client platform, designed to serve different user experiences through a shared backend infrastructure. Client applications include:
All client applications consume the same TuranBilgi APIs (REST, GraphQL, and WebSockets), ensuring: