Codebase Structure

Codebase structure

Top-level map

Path	Purpose	Evidence
src/miniproto/	Installable Python package and private native extension destination	pyproject.toml, src/miniproto/__init__.py
rust/miniproto/	Rust/PyO3 native extension crate	Cargo.toml, rust/miniproto/Cargo.toml
tools/schema/	Pinned Telegram inputs, updater, parser, generator, binding manifest, and generated-fast-path selection	tools/schema/README.md
tools/docs/	Static Python/Telegram/Rust reference extraction, audits, manifest handling, and site orchestration	tools/docs/__main__.py
tools/bench/	Offline, live, matrix, compatibility, and reporting benchmarks	src/miniproto/_cli.py, docs/development.md
tests/	Offline unit/fake-server/workflow/docs tests plus gated integration/ and stress/ suites	pyproject.toml, tests/integration/README.md
docs/	Canonical authored Markdown, internal THOUGHTS.md, and committed generated reference pages	docs/reference-surface.toml, docs-site/src/content.config.ts
docs-site/	Astro/Starlight presentation, Pagefind, assets, browser acceptance, and ignored static output	docs-site/package.json, docs-site/astro.config.ts
.github/workflows/	CI, docs, schema-upstream, live-benchmark, dispatch-only release construction, and protected OIDC publication	.github/workflows/
plans/	Historical and active implementation plans; not proof of runtime behavior by themselves	plans/README.md, PROGRESS.md

Root PLAN.md, PROGRESS.md, README.md, CHANGELOG.md, SECURITY.md, and CONTRIBUTING.md describe implementation intent, verified progress, public usage, release capabilities, security, and contribution. Documentation-product direction and branding live under docs/project/, especially docs/project/index.md and docs/project/brand.md. Code and current test/config evidence take precedence when an older plan statement disagrees with implementation.

Entry points

• The import surface is src/miniproto/__init__.py, which re-exports the reviewed client, config, storage, session, media, type, error, file-ID, event-loop, and observability APIs.
• Application code constructs Client(ClientConfig(...)); there is no always-running package process or web-server main. Lifecycle starts through connect(), async with Client(...), or caller-owned event_loop.run().
• Generated raw imports enter through miniproto.raw.functions, miniproto.raw.types, and their namespace facades. Implementation shards under src/miniproto/raw/_function_shards/ and _types_shards/ are generator-owned.
• Operational tools enter through [project.scripts] in pyproject.toml; src/miniproto/_cli.py bridges installed launchers to tools.schema, tools.docs, tools.bench, tools.release_check, and tools.release_artifacts modules.
• The native module is built from rust/miniproto/src/lib.rs and imported privately as miniproto._native; Python wrappers own capability selection and fallbacks.

Python module boundaries

Boundary	Owns	Must not own	Evidence
auth/	RSA/DH key exchange, DC configuration, phone/bot/2FA authorization	Message/media framework helpers	src/miniproto/auth/
connection/	TCP transports, proxy handshakes, framing, sender lifecycle, correlation, quick ACK	Persistent domain models or application routing	src/miniproto/connection/
mtproto/ and tl/	MTProto envelopes/state/service constructors and generic/generated TL codecs	Socket ownership or high-level client workflows	src/miniproto/mtproto/, src/miniproto/tl/
session/	Typed session state, atomic storage, peer merging, portable strings	Telegram network calls	src/miniproto/session/
updates/	Cursor/deduplication state, gap recovery, public queues, handlers	Application exactly-once semantics	src/miniproto/updates/
media/	Upload/download/CDN/integrity/scheduling primitives	Broad media ergonomics reserved for mpgram	src/miniproto/media/, docs/media.md
raw/	Generated Layer 228 Python bindings, registries, facades, and shards	Handwritten business logic	tools/schema/generate.py, src/miniproto/raw/
client.py	Public orchestration across auth, senders, peers, updates, messages, sessions, and media pools	Schema definition or low-level cryptographic implementation	src/miniproto/client.py
observability.py and security/	Local logging/metrics/resource snapshots and redaction	External telemetry transport or secret storage	src/miniproto/observability.py, src/miniproto/security/redaction.py

Generated and authored ownership

• Never hand-edit raw binding shards, src/miniproto/raw/functions.py, src/miniproto/raw/types.py, their stubs/registry, rust/miniproto/src/generated_tl.rs, or src/miniproto/tl/fast_metadata.py; change pinned inputs/generators and run miniproto-schema-generate.
• Never hand-edit docs/reference/**; change source docstrings, schema metadata, Rust docs, or docs generators and run miniproto-docs.
• Handwritten pages outside docs/reference/ remain canonical authored sources. docs/THOUGHTS.md is internal and deliberately excluded from the site.
• docs-site/dist/, .astro/, Pagefind output, rustdoc JSON, caches, wheels, and local native build products are derived artifacts and are not source conventions.

Naming and organization rules

• Python source/test files and packages use lowercase snake_case; public Python types use PascalCase, and private helpers/modules use a leading underscore where appropriate.
• Rust modules use lowercase snake_case; types/variants use PascalCase; constants use UPPER_SNAKE_CASE.
• Generated Telegram Python class names translate qualified TL names to PascalCase, while exact Telegram qualified names remain in constructor metadata and reference headings.
• Documentation content is organized by user journey (start, guides, concepts, recipes, faq, project) while generated references are organized by language.
• Python uses absolute miniproto... imports for package boundaries; package __all__ declarations define reviewed public facades.

Evidence

• src/miniproto/__init__.py
• src/miniproto/_cli.py
• src/miniproto/client.py
• tools/schema/README.md
• tools/docs/__main__.py
• docs/reference-surface.toml
• docs-site/src/content.config.ts
• pyproject.toml