# pys-info/tracify architecture

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

- Interactive diagram: https://gitdiagram.com/pys-info/tracify
- Repository: https://github.com/pys-info/tracify

## Overview

##### Project Type and Purpose
- This is a Django‐compatible Python package (“tracify”) that hooks into a Django project to capture errors/exceptions and fan out notifications to multiple channels or persist them in a database.
- It is an open-source tool (a pluggable Django app), not a standalone front-end/backend service.

##### File/Module Structure Highlights
- Top-level modules:
- tracify/         – core app logic
- tracify/channels – channel abstractions + specific backends (discord, slack, teams, email, db)
- tracify/db_backend – database model, migrations, views (optional admin UI)
- tracify/signals   – hook that listens for Django signals (errors) and dispatches to channels via a factory
- example/         – sample Django project demonstrating integration
- Configuration files:
- settings.py in example shows how TRACIFY_CHANNELS_CONFIGURATION is defined
- manage.py, asgi.py, wsgi.py – standard Django entry points
- Tests and docs under docs/ and tracify/tests/ illustrate usage patterns and edge-cases.

##### Key Insights from README
- The package registers itself via INSTALLED_APPS and uses Django’s signal/receiver mechanism to catch errors in real time.
- Uses a Channel Factory pattern to instantiate the right channel backend when an error occurs.
- Supports external notification services (Discord, Slack, MS Teams, Email) and an internal persistence “DB” channel.

##### Main Components
a. “Client Django Project” – your app where you install tracify in INSTALLED_APPS
b. Django Error Signal Bus – the place where exceptions or custom signals fire
c. tracify.signals – the receiver that picks up signals
d. Channel Factory – decides which ChannelBackend(s) to instantiate based on TRACIFY_CHANNELS_CONFIGURATION
e. Channel Backends – implement a uniform interface:
- DiscordChannel
- TeamsChannel
- SlackChannel
- EmailChannel
- DBChannel (persists to tracify_db backend)
f. External Services – Discord Webhook API, Slack Webhook API, Teams Webhook API, SMTP server for Email
g. Database – your Django database with tracify_db tables (for DBChannel)

##### Relationships & Data Flow
1. An exception occurs in your Django project → Django’s signal dispatcher broadcasts an error signal.
2. tracify.signals receives the error → passes error metadata into ChannelFactory.
3. ChannelFactory reads TRACIFY_CHANNELS_CONFIGURATION from settings → instantiates one or more ChannelBackend instances.
4. Each ChannelBackend.send(error_payload) method is called:
– DiscordChannel, SlackChannel, TeamsChannel: POST JSON to respective webhook URLs
– EmailChannel: compose and send email via SMTP
– DBChannel: write a new record in the tracify_db table
5. Optionally, the DBBackend exposes an admin UI (tracify/db_backend/views.py) to browse persisted errors.

##### Architectural Patterns & Principles
- Observer Pattern: Django’s builtin signals + tracify.signals act as observers of error events.
- Factory Pattern: tracify.channels.channels_factory dynamically creates channel handlers.
- Pluggability/Modularity: each backend lives in its own module under tracify.channels.backends and implements a uniform interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Django Project"
        direction TB
        clientApp["Client Django App"]:::internal
        settings["settings.py\n(TRACIFY_CHANNELS_CONFIGURATION)"]:::internal
        asgi["asgi.py"]:::internal
        wsgi["wsgi.py"]:::internal
        urls["urls.py"]:::internal
        manage["manage.py"]:::internal
    end

    subgraph "tracify Core Package"
        direction TB
        appSettings["app_settings.py"]:::internal
        apps["apps.py"]:::internal
        signals["signals.py\n(Django Receiver)"]:::internal
        factory["channels_factory.py\n(ChannelFactory)"]:::extension
        channelInterface["channel.py\n(Channel Interface)"]:::extension
        templates["issue_notifier.html"]:::internal

        subgraph "Channel Backends"
            direction TB
            discord["discord.py\n(DiscordChannel)"]:::extension
            slack["slack.py\n(SlackChannel)"]:::extension
            teams["teams.py\n(TeamsChannel)"]:::extension
            email["email.py\n(EmailChannel)"]:::extension
            dbch["db.py\n(DBChannel)"]:::extension
        end

        subgraph "DB Backend Modules"
            direction TB
            dbBackend["db_backend/"]:::internal
            models["models.py"]:::internal
            migrations["0001_initial.py"]:::internal
            adminFile["admin.py"]:::internal
            views["views.py"]:::internal
        end
    end

    subgraph "External Services"
        direction TB
        discordAPI["Discord Webhook API"]:::external
        slackAPI["Slack Webhook API"]:::external
        teamsAPI["Teams Webhook API"]:::external
        smtp["SMTP Server"]:::external
    end

    db["Django Database\n(tracify DB tables)"]:::external

    clientApp -->|"Exception Occurs"| signals
    signals -->|"Pass error to"| factory
    factory -->|"Instantiate"| discord
    factory --> slack
    factory --> teams
    factory --> email
    factory --> dbch

    discord -->|"POST JSON"| discordAPI
    slack -->|"POST JSON"| slackAPI
    teams -->|"POST JSON"| teamsAPI
    email -->|"SMTP Send"| smtp
    dbch -->|"Write Record"| db

    dbBackend --> views
    views --> db

    click clientApp "https://github.com/pys-info/tracify/tree/main/example/example/"
    click settings "https://github.com/pys-info/tracify/blob/main/example/example/settings.py"
    click asgi "https://github.com/pys-info/tracify/blob/main/example/example/asgi.py"
    click wsgi "https://github.com/pys-info/tracify/blob/main/example/example/wsgi.py"
    click urls "https://github.com/pys-info/tracify/blob/main/example/example/urls.py"
    click manage "https://github.com/pys-info/tracify/blob/main/example/manage.py"

    click appSettings "https://github.com/pys-info/tracify/blob/main/tracify/app_settings.py"
    click apps "https://github.com/pys-info/tracify/blob/main/tracify/apps.py"
    click signals "https://github.com/pys-info/tracify/blob/main/tracify/signals.py"
    click factory "https://github.com/pys-info/tracify/blob/main/tracify/channels/channels_factory.py"
    click channelInterface "https://github.com/pys-info/tracify/blob/main/tracify/channels/channel.py"
    click discord "https://github.com/pys-info/tracify/blob/main/tracify/channels/backends/discord.py"
    click slack "https://github.com/pys-info/tracify/blob/main/tracify/channels/backends/slack.py"
    click teams "https://github.com/pys-info/tracify/blob/main/tracify/channels/backends/teams.py"
    click email "https://github.com/pys-info/tracify/blob/main/tracify/channels/backends/email.py"
    click dbch "https://github.com/pys-info/tracify/blob/main/tracify/channels/backends/db.py"

    click dbBackend "https://github.com/pys-info/tracify/tree/main/tracify/db_backend/"
    click models "https://github.com/pys-info/tracify/blob/main/tracify/db_backend/models.py"
    click migrations "https://github.com/pys-info/tracify/blob/main/tracify/db_backend/migrations/0001_initial.py"
    click adminFile "https://github.com/pys-info/tracify/blob/main/tracify/db_backend/admin.py"
    click views "https://github.com/pys-info/tracify/blob/main/tracify/db_backend/views.py"

    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef extension fill:#FCF3CF,stroke:#B7950B,color:#6E2C00
    classDef external fill:#D5F5E3,stroke:#117A65,color:#145A32
```
