swadhin / git-discord-bot public
/ git-discord-bot / ARCHITECTURE.md
swadhinbiswas feat: complete DevPulse production developer operating system for Discord · 9/6/2026
4a8d707
95 lines · 5.3 KB
Raw Download

DevPulse System Architecture

DevPulse (internal codename: RavenDev) is designed from first principles as an enterprise-grade, multi-tenant developer operating system for Discord.

                  +-----------------------------------+
                  |         Discord Gateway           |
                  +-----------------+-----------------+
                                    |
                            (Events / Interactions)
                                    v
                  +-----------------------------------+
                  |          apps/bot (Discord)       |
                  |  - Slash Commands (16 suites)     |
                  |  - Interactive Buttons            |
                  |  - Category Select Menus          |
                  |  - Zero-Log Secret Scanner        |
                  +--------+------------------+-------+
                           |                  |
              (Service Calls)        (Distributed Locks)
                           v                  v
    +--------------------------------+  +--------------------------------+
    |         Domain Packages        |  |          Cache & Jobs          |
    |  - @devpulse/github            |  |  - @devpulse/cache             |
    |  - @devpulse/devtools          |  |    (Upstash Redis / Memory)    |
    |  - @devpulse/analytics         |  |  - @devpulse/scheduler         |
    |  - @devpulse/security          |  |    (Periodic Ticks, Mutex)     |
    |  - @devpulse/monitoring        |  +--------------------------------+
    |  - @devpulse/news              |
    |  - @devpulse/trending          |
    +----------------+---------------+
                     |
            (Relational Queries)
                     v
    +--------------------------------+  +--------------------------------+
    |        Database Layer          |  |          Fastify API           |
    |  - @devpulse/database          |  |  - apps/api                    |
    |  - Turso / libSQL              |  |  - /health, /ready, /metrics   |
    |  - Drizzle ORM Schema          |  +--------------------------------+
    +--------------------------------+

1. Multi-Tenant Isolation Model

All persistent records are strictly bound to either a Discord Server (guildId) or a Discord User (userId).

  • Tables (repositories, monitors, monitor_results, projects, reminders, standups, server_settings) enforce guild_id foreign keys with ON DELETE CASCADE.
  • Data access layers execute tenant authorization assertions (assertTenantOwnership(entityGuildId, requestGuildId)).
  • Cross-tenant queries are structurally prevented by scoped composite indices:
    • (guild_id, name) for projects
    • (guild_id, full_name) for repositories
    • (guild_id, user_id, date) for daily standups

2. Caching & Resilience Strategy

  • Source of Truth: Turso / libSQL is the primary persistent database. Redis is never used as the single source of truth.
  • Provider Abstraction: @devpulse/cache implements CacheProvider, automatically selecting @upstash/redis in production environments or falling back to an in-memory TTL store for local development and tests.
  • Cache-Aside with Mutex Locking: High-latency external endpoints (such as GitHub commits or OSV vulnerability queries) utilize getOrSet() with distributed mutex locks to prevent cache stampedes under concurrent user load.
  • Configured TTLs:
    • GitHub Repo Metadata: 300 seconds
    • GitHub Commits & PRs: 300 seconds
    • GitHub Releases: 1,800 seconds
    • OSV / CVE Advisories: 86,400 seconds (24 hours)
    • Tech News: 900 seconds (15 minutes)
    • Trending Repositories: 1,800 seconds (30 minutes)

3. Asynchronous Worker & Scheduler

To avoid blocking Discord interaction threads:

  • Synthetic website monitoring pings and reminder checks are decoupled into @devpulse/scheduler.
  • Scheduled intervals run every 30 seconds.
  • Mutex locks (SET lock:scheduler:monitors NX EX 50) guarantee that in a multi-instance container cluster, exactly one worker instance processes due checks at any given tick.
  • Due reminders and status changes (e.g. healthy -> down or down -> recovered) trigger asynchronous event callbacks that format rich embeds and dispatch them to the server's configured alert channel.

4. Security & Defensive Engineering

  1. SSRF Guard (@devpulse/devtools/src/ssrf.ts):
    • Outbound HTTP, DNS, and SSL requests undergo URL validation.
    • Private IPv4 blocks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16) are blocked.
    • Private IPv6 ranges (::1, fc00::/7, fe80::/10) and IPv4-mapped IPv6 ranges are blocked.
    • Cloud metadata hosts (169.254.169.254, metadata.google.internal) are blocked.
  2. Zero-Log Secret Scanner (@devpulse/security/src/secrets.ts):
    • Scans non-bot messages for token patterns (GitHub PATs, AWS access keys, Discord bot tokens, RSA private keys, database connection strings).
    • Generates a one-way SHA-256 fingerprint for operational tracking without storing or logging the sensitive token.
    • Warns the author with an interactive [Delete Leaked Message] button and rotation recommendations.
  3. Structured Logging & Redaction (@devpulse/logger):
    • Pino redacts *.token, *.apiKey, *.secret, *.password, and authorization headers by default.