telegram-edge/INTENT.md

INTENT.md — telegram-edge

Purpose

telegram-edge provides the Telegram-facing interface layer for the Coulomb.social ecosystem.

Its purpose is to make Telegram usable as a primary social surface for publishing, community interaction, automation, and service access while keeping Coulomb-controlled systems authoritative for identity, knowledge, content, product logic, and durable state.

The repository exists to isolate Telegram-specific capabilities, constraints, and protocols behind a controlled edge so that Coulomb and HelixForge can use Telegram deeply without becoming structurally dependent on it.

---

Primary Utility

telegram-edge should enable Coulomb.social and related systems to:

• publish and distribute content through Telegram channels, groups, communities, and bots;
• receive and normalize relevant interactions originating from Telegram;
• support conversational and command-based access to Coulomb and HelixForge capabilities;
• expose selected services through Telegram-native interaction patterns, including bots and Mini Apps where useful;
• connect Telegram identities to Coulomb identities without making Telegram the identity authority;
• support community operations such as discussions, topics, moderation, notifications, feedback, and membership flows;
• provide a controlled boundary for automation and agent participation;
• preserve observability, auditability, consent, and policy enforcement at the platform edge;
• make Telegram replaceable or complementable by other social surfaces over time.

---

Intended Users

Primary users are:

• Coulomb.social community members interacting through Telegram;
• maintainers and community operators publishing or moderating through Telegram;
• Coulomb and HelixForge services that need to send or receive Telegram interactions;
• automation and software agents acting through explicitly permitted Telegram interfaces;
• developers integrating Telegram capabilities without coupling domain systems directly to Telegram APIs.

---

Strategic Role in the System

telegram-edge is an edge adapter and social interface boundary.

It should translate between Telegram-native concepts and Coulomb-native capabilities while preventing Telegram-specific assumptions from leaking into the wider ecosystem.

Conceptually:

People / Telegram Clients
          │
          ▼
     Telegram Platform
          │
          ▼
     telegram-edge
          │
   ┌──────┼────────┐
   ▼      ▼        ▼
Content  Identity  Services
   │      │        │
   └──────┴────────┘
          │
          ▼
   Coulomb / HelixForge

Coulomb-controlled systems remain the source of truth. Telegram is treated as a powerful but external interaction and distribution environment.

---

Responsibilities

telegram-edge owns responsibility for:

1. Telegram integration

   • Bot API integration;
   • channel, group, topic, community, and message interaction;
   • Telegram login and identity-linking integration where adopted;
   • Mini App integration boundaries where adopted;
   • Telegram-specific payment or monetization interfaces where adopted.

2. Publishing

   • transforming canonical Coulomb content into Telegram-compatible publications;
   • scheduling, updating, linking, and tracking publications;
   • preserving references back to canonical content where appropriate.

3. Inbound interaction

   • receiving Telegram updates and events;
   • validating and normalizing them;
   • mapping them into platform-independent commands, events, requests, or contributions.

4. Community interface

   • supporting moderation, feedback, discussions, subscriptions, notifications, and community workflows;
   • exposing Telegram capabilities without embedding community policy into Telegram-specific code.

5. Automation boundary

   • providing explicit interfaces for bots and agents;
   • separating automated behavior from human identity;
   • enforcing permissions, rate limits, consent, and traceability.

6. Platform risk containment

   • isolating Telegram API changes and platform constraints;
   • limiting unnecessary retention of Telegram-originated data;
   • supporting export, replay, reconciliation, and migration where practical;
   • preventing Telegram from becoming an accidental system of record.

---

Strategic Boundaries

In Scope

telegram-edge is responsible for the translation, integration, and operational boundary between Telegram and Coulomb-controlled systems.

It may contain:

• Telegram API clients and webhooks;
• message and event adapters;
• publication pipelines;
• Telegram-specific rendering;
• identity-link mappings;
• bot command routing;
• Mini App integration endpoints;
• moderation adapters;
• telemetry and delivery evidence;
• platform capability discovery;
• Telegram-specific configuration and policy enforcement.

Out of Scope

telegram-edge should not become:

• the canonical content repository;
• the canonical knowledge store;
• the authoritative user or organization directory;
• the primary business-logic layer;
• a general-purpose social network backend;
• the canonical community governance system;
• an unrestricted archive or scraper of Telegram conversations;
• an AI training corpus derived from Telegram activity;
• a replacement for domain services already owned elsewhere in the Coulomb or HelixForge ecosystem.

Where durable state is required, the authoritative representation should normally live outside Telegram and outside this repository.

---

Design Principles

1. Telegram is a Surface, Not the System

The value of Telegram lies in reach, interaction, convenience, and native social capabilities.

Core knowledge, identity, product state, and business logic remain under Coulomb control.

2. Keep Platform Coupling at the Edge

Telegram-specific identifiers, API structures, limits, formatting rules, and lifecycle behavior should terminate inside telegram-edge.

Downstream systems should consume stable Coulomb-native interfaces wherever practical.

3. Canonical First, Publish Second

Important content should be created or persisted canonically before or alongside publication to Telegram.

A Telegram post may be a complete user experience, but it should not silently become the only durable copy of strategically important information.

4. Bidirectional, but Deliberate

Telegram should support both outbound publishing and inbound participation.

Inbound information should cross into canonical systems only through explicit, inspectable flows with appropriate validation, classification, consent, and provenance.

5. Human and Agent Participation Are First-Class but Distinct

The edge should support people, bots, and software agents while preserving clear identity, authorization, attribution, and audit boundaries between them.

Automation should never depend on pretending to be an ordinary human participant.

6. Consent and Data Boundaries Are Explicit

Telegram-originated data should only be retained, promoted into knowledge systems, or exposed to automated processing when there is a defined purpose and lawful basis.

Content intended for AI-assisted processing, reuse, or knowledge promotion should have an explicit path rather than being harvested indiscriminately from community activity.

7. Prefer Capability Detection Over Assumption

Telegram evolves quickly.

Integrations should model platform capabilities explicitly and degrade gracefully when capabilities, permissions, limits, or commercial terms change.

8. Operations Must Be Observable

Important inbound and outbound interactions should be traceable through logs, correlation identifiers, delivery state, errors, retries, and relevant platform identifiers without collecting unnecessary personal data.

9. Failure Must Not Corrupt Canonical State

Telegram outages, API failures, rate limits, deleted messages, changed permissions, or account restrictions must not compromise authoritative Coulomb state.

Publishing and interaction flows should be retryable and, where appropriate, idempotent.

10. Preserve Exit Options

The architecture should make it possible to add or replace social surfaces such as web, RSS, email, ActivityPub, Matrix, Discord, or future platforms without redesigning Coulomb's core systems.

---

Maturity Target

The long-term target is a production-grade social edge through which Telegram can function as a primary community and interaction surface for Coulomb.social while remaining an external, replaceable platform.

A mature telegram-edge should provide:

• reliable bidirectional integration;
• consistent publication workflows;
• identity-aware interaction;
• secure bot and agent access;
• auditable community automation;
• explicit consent and data-handling controls;
• measurable delivery and interaction state;
• resilience against Telegram API and policy changes;
• clean interfaces to canonical Coulomb and HelixForge services.

---

Guiding Statement

Use Telegram deeply as a social surface without allowing Telegram to become the system.

telegram-edge should make Telegram feel native to the Coulomb.social community while preserving the sovereignty, portability, and architectural integrity of the ecosystem behind it.

---

Stability Note

This file describes the intended role and enduring architectural purpose of telegram-edge.

INTENT is stable and aspirational. SCOPE is actual and evolutionary.

Implementation choices, supported Telegram features, APIs, workflows, deployment models, and current limitations belong in the repository's evolving scope, architecture, specifications, and work plans. They may change without changing this intent as long as telegram-edge continues to provide a controlled, replaceable Telegram social boundary for the Coulomb.social ecosystem.