# synapsefi/demo.slackbot architecture

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

- Interactive diagram: https://gitdiagram.com/synapsefi/demo.slackbot
- Repository: https://github.com/synapsefi/demo.slackbot

## Overview

##### Project Type and Purpose
- demo.slackbot is a full-stack Slack integration proof-of-concept that combines a lightweight web server (for user registration) with a Slack bot event loop.
- It leverages Synapse’s API for automated savings operations (see disclaimer: not production-grade).

##### File Structure Analysis
- Top-level:
– Dockerfile, config directory (app.ini, nginx.conf, supervisor.conf), requirements.txt
– app/ folder: the main Python code, static assets, HTML templates
– samples.md (Slack message format examples)
- app/ contains:
– app.py: HTTP server entry point (likely Flask) serving templates/static
– slack_event_loop.py: long-running process subscribing to Slack events
– bot.py + commands.py: core Slack command handlers
– db.py, models.py, schema.sql: local database layer and schema definitions
– core/: wrapper around Synapse API calls and business logic
– templates/register.html + static/register.{css,js}: user registration front end

##### Architecture Insights from README
- Two runtime modes:
– Non-Docker: run app.py (web) and slack_event_loop.py (bot) separately
– Docker: container bundles web server behind Nginx + Supervisor to manage both processes
- No mention of message queue: the event loop directly invokes command handlers and core logic.

##### Main Components
a. External Services
- Slack Events API / Webhooks – sends user commands and events
- Synapse API – external banking/savings service
b. Internal Services
- HTTP Server (app.py + Flask framework)
- Slack Event Loop (slack_event_loop.py)
- Bot Logic Layer (commands.py, bot.py)
- Core Business Logic (app/core/)
- Persistence Layer (db.py, models.py, local SQL database)
- Front-end Assets (templates + static files)
c. Infrastructure Components (Docker mode)
- Nginx reverse proxy (nginx.conf)
- Supervisor process manager (supervisor.conf)
- Docker container

##### Component Relationships and Data Flows
- User → Slack UI → Slack Events API → Slack Event Loop → Bot Logic → Core Logic → Synapse API → Core Logic → Persistence Layer → Slack Event Loop → Slack UI (responses)
- User Web Browser → HTTP Server → Templates/Static → HTTP Server → Database (user registrations)
- Supervisor manages both the HTTP Server and Slack Event Loop processes; Nginx routes incoming HTTP traffic on port 80 to the HTTP Server.

##### Architectural Patterns & Principles
- Separation of Concerns:
– Web interface vs. bot event loop
– API integration (core/) vs. transport layer (bot.py/commands.py)
- Modular services: easy to swap Slack or Synapse implementations
- Containerization for reproducible deployments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External services
    SlackEventsAPI["Slack Events API"]:::external
    SynapseAPI["Synapse API"]:::external
    UserBrowser["User Web Browser"]:::external

    %% Docker container
    subgraph "Docker Container"
        direction TB
        Nginx["Nginx Proxy"]:::infra
        Supervisor["Supervisor"]:::infra

        subgraph "Web Server"
            direction TB
            HTTPServer["HTTP Server (Flask App)"]:::internal
            TemplatesStatic["Templates & Static"]:::internal
            DBAdapter["DB Adapter"]:::internal
            LocalDB["Local SQL DB"]:::internal
        end

        subgraph "Slack Bot Service"
            direction TB
            EventLoop["Slack Event Loop"]:::internal
            subgraph "Bot Logic Layer"
                direction TB
                CoreBot["Bot Orchestration"]:::internal
                CommandHandlers["Command Handlers"]:::internal
            end
            CoreLogic["Core Business Logic"]:::internal
        end

        %% Infrastructure flows
        Nginx -->|routes HTTP traffic| HTTPServer
        Supervisor -->|manages| HTTPServer
        Supervisor -->|manages| EventLoop
    end

    %% User and Web flows
    UserBrowser -->|HTTP Request| Nginx
    HTTPServer -->|serves| TemplatesStatic
    HTTPServer -->|reads/writes| LocalDB
    TemplatesStatic -->|static files| UserBrowser

    %% Bot flows
    SlackEventsAPI -->|webhooks| EventLoop
    EventLoop -->|dispatch| CoreBot
    CoreBot -->|invoke| CommandHandlers
    CommandHandlers -->|call| CoreLogic
    CoreLogic -->|requests| SynapseAPI
    SynapseAPI -->|response| CoreLogic
    CoreLogic -->|updates| LocalDB
    CoreLogic -->|response| CommandHandlers
    CommandHandlers -->|response| EventLoop
    EventLoop -->|response| SlackEventsAPI

    %% Click events
    click HTTPServer "https://github.com/synapsefi/demo.slackbot/blob/master/app/app.py"
    click EventLoop "https://github.com/synapsefi/demo.slackbot/blob/master/app/slack_event_loop.py"
    click CoreBot "https://github.com/synapsefi/demo.slackbot/blob/master/app/bot.py"
    click CommandHandlers "https://github.com/synapsefi/demo.slackbot/blob/master/app/commands.py"
    click CoreLogic "https://github.com/synapsefi/demo.slackbot/tree/master/app/core/"
    click DBAdapter "https://github.com/synapsefi/demo.slackbot/blob/master/app/db.py"
    click LocalDB "https://github.com/synapsefi/demo.slackbot/blob/master/app/schema.sql"
    click TemplatesStatic "https://github.com/synapsefi/demo.slackbot/blob/master/app/templates/register.html"
    click TemplatesStatic "https://github.com/synapsefi/demo.slackbot/blob/master/app/static/register.css"
    click TemplatesStatic "https://github.com/synapsefi/demo.slackbot/blob/master/app/static/register.js"
    click Nginx "https://github.com/synapsefi/demo.slackbot/blob/master/config/nginx.conf"
    click Supervisor "https://github.com/synapsefi/demo.slackbot/blob/master/config/supervisor.conf"
    click Dockerfile "https://github.com/synapsefi/demo.slackbot/tree/master/Dockerfile"

    %% Styles
    classDef external fill:#cce5ff,stroke:#4da3ff,color:#004085
    classDef internal fill:#d4edda,stroke:#28a745,color:#155724
    classDef infra fill:#fff3cd,stroke:#ffecb5,color:#856404
```
