Skip to content
Learnille Documentation

Architecture Decision Records (ADRs)

Architecture Decision Records (ADRs)

Overview

Architecture Decision Records (ADRs) capture important architectural decisions made during the development of the Learnille platform. Each ADR describes the context, decision, and consequences of a significant architectural choice.

ADR Template

ADR [Number]: [Title]

Date: YYYY-MM-DD

Status: [Proposed | Accepted | Rejected | Deprecated | Superseded]

Context: [Describe the context and problem being solved]

Decision: [Describe the decision that was made]

Consequences: [Describe the positive and negative consequences of the decision]

Alternatives Considered: [List alternative solutions that were considered]

Related ADRs: [Links to related ADRs]

Current ADRs

ADR 001: Technology Stack Selection

Date: 2024-01-15

Status: Accepted

Context: We needed to choose a technology stack for building the Learnille platform that would support rapid development, scalability, and maintainability. The platform requires handling user authentication, course management, payments, and real-time features.

Decision: We decided to use:

  • Frontend: React with TypeScript (Vite)
  • Backend: Node.js with NestJS framework
  • Database: PostgreSQL (Self-Hosted)
  • Cache & Queue: Redis / BullMQ
  • Search: OpenSearch for vector and course search
  • Storage: Cloudflare R2 (S3 API compatible) / MinIO locally
  • Hosting & Observability: Self-Hosted Infrastructure with New Relic APM/Logs & Sentry

Consequences:

  • Positive:

    • Strong TypeScript support improves code quality and developer experience
    • NestJS provides excellent structure and scalability
    • PostgreSQL offers robust relational data management
    • Cloudflare R2 eliminates egress bandwidth costs
    • Self-hosting provides operational autonomy and predictable costs
    • New Relic provides centralized APM and log aggregation

  • Negative:

    • Self-hosting requires maintaining server deployment scripts and backups
    • Team operational responsibility for infrastructure health

Alternatives Considered:

  • Python/Django: More mature but slower development
  • Ruby on Rails: Rapid development but less scalable
  • Go: High performance but smaller ecosystem

ADR 002: Microservices Architecture

Date: 2024-01-20

Status: Accepted

Context: As the platform grows, we need to ensure scalability and maintainability. The monolithic architecture was becoming complex to manage and deploy.

Decision: We decided to adopt a microservices architecture with the following services:

  • User Service
  • Course Service
  • Payment Service
  • Notification Service
  • Analytics Service

Consequences:

  • Positive:

    • Independent deployment and scaling
    • Technology diversity per service
    • Better fault isolation
    • Smaller, focused teams

  • Negative:

    • Increased complexity in deployment and monitoring
    • Distributed system challenges (consistency, latency)
    • Higher operational overhead

Alternatives Considered:

  • Monolithic with modules: Simpler but less scalable
  • Serverless functions: Good scalability but vendor lock-in

ADR 003: API Design with REST

Date: 2024-01-25

Status: Accepted

Context: We needed a consistent API design that would be easy to understand, version, and maintain for both internal and external consumers.

Decision: We chose RESTful API design with the following principles:

  • Resource-based URLs
  • Standard HTTP methods
  • JSON responses
  • OpenAPI/Swagger documentation
  • Versioning through URL paths (/api/v1/)

Consequences:

  • Positive:

    • Widely adopted and understood
    • Good tooling support
    • Easy to cache and debug
    • Works well with HTTP infrastructure

  • Negative:

    • Can lead to over-fetching/under-fetching
    • Multiple round trips for complex data
    • Less efficient for mobile networks

Alternatives Considered:

  • GraphQL: More flexible but complex
  • gRPC: High performance but language-specific

ADR 004: Database Schema Design

Date: 2024-02-01

Status: Accepted

Context: We needed to design a database schema that supports the core business entities while maintaining data integrity and performance.

Decision: We chose PostgreSQL with the following design principles:

  • Normalized schema to reduce redundancy
  • UUID primary keys for scalability
  • JSONB columns for flexible data
  • Proper indexing strategy
  • Foreign key constraints for data integrity

Consequences:

  • Positive:

    • Strong data consistency
    • Excellent JSON support for flexible data
    • Advanced querying capabilities
    • Good performance with proper indexing

  • Negative:

    • More complex queries for denormalized data
    • Migration complexity
    • Learning curve for advanced features

Alternatives Considered:

  • MongoDB: Flexible schema but weaker consistency
  • MySQL: Familiar but less advanced features

ADR 005: Authentication with JWT

Date: 2024-02-05

Status: Accepted

Context: We needed a secure and scalable authentication system that works well with microservices and mobile applications.

Decision: We implemented JWT-based authentication with:

  • Access tokens with short expiration (1 hour)
  • Refresh tokens for session management
  • Role-based access control (RBAC)
  • Secure token storage

Consequences:

  • Positive:

    • Stateless authentication
    • Works well with microservices
    • Good mobile app support
    • Industry standard

  • Negative:

    • Token revocation complexity
    • No server-side session invalidation
    • Token size can be large

Alternatives Considered:

  • Session-based auth: Server state management
  • OAuth 2.0: More complex but more secure

ADR 006: Payment Processing with Stripe

Date: 2024-02-10

Status: Accepted

Context: We needed a reliable payment processing solution that handles various payment methods and provides good developer experience.

Decision: We integrated Stripe for payment processing with:

  • Support for multiple payment methods
  • Webhook handling for payment events
  • PCI compliance
  • Subscription management

Consequences:

  • Positive:

    • Excellent developer documentation
    • Comprehensive API
    • Strong security and compliance
    • Good international support

  • Negative:

    • Transaction fees
    • Dependency on third-party service
    • Webhook reliability concerns

Alternatives Considered:

  • PayPal: Higher fees, less developer-friendly
  • Braintree: Good but more complex integration

ADR 007: Deployment with Kubernetes

Date: 2024-02-15

Status: Proposed

Context: We need a container orchestration solution that can handle our microservices deployment, scaling, and management.

Decision: We are considering Kubernetes for container orchestration with:

  • Automated deployment and scaling
  • Service discovery and load balancing
  • Configuration management
  • Monitoring and logging integration

Consequences:

  • Positive:

    • Industry standard for container orchestration
    • Highly scalable and reliable
    • Rich ecosystem of tools
    • Cloud-agnostic

  • Negative:

    • Steep learning curve
    • Complex setup and maintenance
    • Resource overhead

Alternatives Considered:

  • Docker Compose: Simple but not scalable
  • AWS ECS: AWS-specific, less flexible

ADR Process

Creating a New ADR

  1. Identify Decision: Recognize when an architectural decision needs to be made
  2. Gather Context: Document the problem and constraints
  3. Evaluate Options: Consider multiple alternatives
  4. Make Decision: Choose the best option based on criteria
  5. Document ADR: Create ADR document following the template
  6. Review: Get feedback from team members
  7. Implement: Put the decision into practice
  8. Monitor: Track outcomes and adjust if needed

ADR Status Definitions

  • Proposed: Decision is being considered
  • Accepted: Decision has been made and implemented
  • Rejected: Decision was considered but not chosen
  • Deprecated: Decision is no longer relevant
  • Superseded: Decision has been replaced by another

ADR Maintenance

  • Review ADRs annually for relevance
  • Update status when decisions change
  • Link related ADRs for context
  • Use ADRs for onboarding new team members

Tools and Templates

ADR Creation Script

#!/bin/bash
# Create new ADR
NEXT_NUMBER=$(ls adr-*.md | grep -o '[0-9]\+' | sort -n | tail -1 | awk '{print $1+1}')
FILENAME="adr-$(printf "%03d" $NEXT_NUMBER)-title.md"
cp adr-template.md $FILENAME

ADR Template File (adr-template.md)

# ADR [NUMBER]: [TITLE]


**Date:** $(date +%Y-%m-%d)


**Status:** Proposed


**Context:**
[Describe the context and problem]


**Decision:**
[Describe the decision]


**Consequences:**
[Positive and negative consequences]


**Alternatives Considered:**
[Other options]


**Related ADRs:**
[Links to related ADRs]

ADR 008: Beacon Analytics - Direct Database Writes

Date: 2025-01-15

Status: Accepted

Context: The beacon analytics system tracks user engagement events (impressions, clicks, bounces) for marketplace entities. We needed to decide between:

  1. Direct database writes on each event
  2. Queue-based processing with background workers
  3. Time-series database for analytics data

Current traffic estimate: ~100 events/minute at launch, scaling with user growth.

Decision: We chose direct PostgreSQL writes with the following mitigations:

  • Client-side batching (10 events or 2s timeout)
  • Redis-based deduplication (prevents duplicate DB writes)
  • Rate limiting (50 requests per 5 minutes per IP)
  • Session-based authentication (reduces spam)

Consequences:

  • Positive:

    • Simple architecture, easy to debug
    • No additional infrastructure (queues, workers)
    • Lower latency for real-time dashboards
    • Fewer moving parts to maintain

  • Negative:

    • DB load scales linearly with traffic
    • Potential write contention at high scale
    • No built-in retry mechanism for failed writes

Scaling Triggers: Reconsider this decision when:

  • DB write latency consistently exceeds 50ms
  • Traffic reaches ~1000 concurrent users (~10k events/min)
  • Analytics queries start impacting main DB performance

Migration Path: When scaling is needed:

  1. Phase 1: BullMQ queue with background worker (already in stack)
  2. Phase 2: Batch inserts (100-500 events per query)
  3. Phase 3: TimescaleDB for time-series optimization

Alternatives Considered:

  • BullMQ Queue: Better scalability but added complexity
  • Kafka: Enterprise-grade but overkill for current scale
  • TimescaleDB: Excellent for analytics but migration overhead
  • ClickHouse: High performance but operational complexity

Related ADRs:

  • ADR 001: Technology Stack Selection
  • ADR 004: Database Schema Design