# btw-so/btw architecture

> Architecture diagram of the GitHub repository btw-so/btw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/btw-so/btw
- Repository: https://github.com/btw-so/btw

## Overview

##### Main Components
- Frontend (Writer): This component (located in the “writer” directory) is the main user interface for content creation and editing. It’s a rich client-side application built with modern tools (React, Redux, Sagas, etc.) and has extensive testing and configuration files.
- Backend – Publishing Service (Publisher): The “publisher” folder hosts a Node.js/Express-based server that handles publishing-related routes (index.js, internal.js, sitemap.js), templating with Handlebars (files in the “views” folder), and overall publication logic.
- Background Task Service (Tasks): The “tasks” directory contains another Express-like service that is responsible for handling asynchronous operations like email notifications, OTP processing, note handling, and alerts. It includes services for database operations, queue management, and redis-based notifications.
- Database and External Services: The application requires a PostgreSQL instance (as mentioned by the “btw.sql” file and TASKS_DATABASE_URL environment variable) along with external integrations such as SMTP for email, S3 for media uploads, and possibly Redis (indicated by the tasks/services/redisPublisher file).

##### Relationships and Interactions
- A client (admin user) interacts with the Writer frontend for content creation and configuration.
- The Writer frontend communicates with the Publisher backend to publish content, render pages (including admin and public pages), and manage dynamic routes.
- The Publisher may also interface with the Tasks service for background jobs—such as sending OTP emails, processing queued updates, or alerting.
- Both publisher and tasks services interact with the PostgreSQL database to persist and read data.
- External services (SMTP, S3, possibly Redis) are integrated to provide email deliveries, file storage, and caching/queueing functionalities.

##### Architectural Patterns and Key Details
- Each component is isolated into its own service (following a microservice-like separation), which makes it easier to scale or update components independently.
- The development and production deployment utilize Docker (as seen from the Dockerfiles and docker-compose YAML files in the “deploy” folder and within individual service folders).
- There’s clear separation of concerns: the Writer is focused on the frontend user experience, Publisher handles content delivery and server-side logic, and Tasks manages asynchronous processing.
- Technologies include Express (Node.js) on the backend, Handlebars for server-side templating in Publisher, React along with modern JavaScript/TypeScript tooling for Writer, and various tools for testing (Jest, Cypress, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User Browser"):::external

    subgraph "Frontend Layer"
        F("Writer Frontend"):::frontend
    end

    subgraph "Backend Services"
        B("Publisher Backend"):::backend
        T("Tasks Background Service"):::worker
    end

    subgraph "External Services"
        D("PostgreSQL Database"):::database
        S("SMTP Service"):::external
        S3("S3 Storage"):::external
        R("Redis Cache"):::external
    end

    subgraph "Deployment"
        E("Docker Deployment"):::docker
    end

    U -->|"User_requests"| F
    F -->|"API_call"| B
    B -->|"Background_jobs"| T
    B -->|"DB_access"| D
    T -->|"DB_access"| D
    B -->|"Send_emails"| S
    B -->|"File_uploads"| S3
    T -->|"Queue_cache"| R
    E -->|"Manages"| F
    E -->|"Manages"| B
    E -->|"Manages"| T

    click F "https://github.com/btw-so/btw/tree/main/writer/"
    click B "https://github.com/btw-so/btw/tree/main/publisher/"
    click T "https://github.com/btw-so/btw/tree/main/tasks/"
    click D "https://github.com/btw-so/btw/blob/main/btw.sql"
    click E "https://github.com/btw-so/btw/tree/main/deploy/"

    classDef frontend fill:#AEE1FF,stroke:#1B91EB,stroke-width:2px;
    classDef backend fill:#C2EABD,stroke:#6BBF59,stroke-width:2px;
    classDef worker fill:#D5A6BD,stroke:#A64D79,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#E59866,stroke-width:2px;
    classDef docker fill:#D6EAF8,stroke:#85C1E9,stroke-width:2px;
```
