TG_autoposter/docs/PROJECT_STRUCTURE.md

Project Structure & File Inventory

Complete File Listing

TG_autoposter/
│
├── 📁 .github/
│   └── 📁 workflows/
│       ├── docker.yml                 # Docker build & push CI/CD
│       └── tests.yml                  # Testing & linting CI/CD
│
├── 📁 app/
│   ├── __init__.py                    # Package initialization
│   ├── main.py                        # Bot entry point
│   ├── settings.py                    # Configuration management
│   ├── db.py                          # Database setup & session management
│   │
│   ├── 📁 models/
│   │   ├── __init__.py
│   │   ├── base.py                    # Base model class
│   │   ├── group.py                   # Group model
│   │   ├── message.py                 # Message model
│   │   ├── message_group.py           # Many-to-many relationship
│   │   ├── group_member.py            # Group member tracking
│   │   ├── group_keyword.py           # Keyword-based filtering
│   │   └── group_statistics.py        # Statistics aggregation
│   │
│   ├── 📁 handlers/
│   │   ├── __init__.py
│   │   ├── commands.py                # /start, /help, /create etc
│   │   ├── callbacks.py               # Button callback handlers
│   │   ├── messages.py                # Message text handlers
│   │   ├── telethon_client.py         # Telethon client manager
│   │   ├── hybrid_sender.py           # Bot/Client switching logic
│   │   ├── group_parser.py            # Group member parsing
│   │   ├── group_manager.py           # Group management
│   │   └── schedule.py                # Scheduling commands
│   │
│   ├── celery_config.py               # Celery initialization
│   ├── celery_tasks.py                # Celery task definitions
│   └── scheduler.py                   # APScheduler integration
│
├── 📁 migrations/
│   ├── env.py                         # Alembic environment config
│   ├── script.py.mako                 # Alembic script template
│   ├── alembic.ini                    # Alembic configuration
│   └── 📁 versions/                   # Database migration files
│       ├── 001_initial_schema.py
│       ├── 002_add_members.py
│       └── ... (more migrations)
│
├── 📁 tests/
│   ├── __init__.py
│   ├── conftest.py                    # Pytest fixtures
│   ├── test_handlers.py               # Handler tests
│   ├── test_models.py                 # Model tests
│   └── test_tasks.py                  # Celery task tests
│
├── 📁 docs/
│   ├── DOCKER_CELERY.md               # Detailed Docker/Celery guide
│   ├── DOCKER_QUICKSTART.md           # Quick reference
│   ├── DOCKER_CELERY_SUMMARY.md       # Feature summary
│   ├── TELETHON.md                    # Telethon integration guide
│   ├── API.md                         # API documentation (optional)
│   └── ARCHITECTURE.md                # Architecture details
│
├── 📁 scripts/
│   ├── docker.sh                      # Docker management script
│   ├── Makefile                       # Make automation targets
│   └── quickstart.sh                  # Quick startup automation
│
├── 📁 logs/
│   └── .gitkeep                       # Logs directory (git tracked)
│
├── 📁 sessions/
│   └── .gitkeep                       # Telegram sessions (local only)
│
├── 📁 backups/
│   └── .gitkeep                       # Database backups
│
├── 🐳 Dockerfile                      # Docker image definition
├── 🐳 docker-compose.yml              # Development composition
├── 🐳 docker-compose.prod.yml         # Production composition
├── 🐳 .dockerignore                   # Docker build exclusions
│
├── ⚙️ .env.example                    # Environment variables template
├── ⚙️ .gitignore                      # Git exclusions
├── ⚙️ .pre-commit-config.yaml         # Pre-commit hooks
├── ⚙️ renovate.json                   # Dependency update automation
├── ⚙️ pyproject.toml                  # Modern Python config
│
├── 📝 README.md                       # Project overview & quick start
├── 📝 DEVELOPMENT.md                  # Development guide
├── 📝 PRODUCTION_DEPLOYMENT.md        # Production deployment guide
├── 📝 IMPROVEMENTS_SUMMARY.md         # This file's companion
├── 📝 PROJECT_STRUCTURE.md            # This file
│
├── 📦 requirements.txt                # Production dependencies
├── 📦 requirements-dev.txt            # Development dependencies
│
├── 📄 LICENSE                         # MIT License
├── 📄 CODE_OF_CONDUCT.md              # Contributing guidelines
└── 📄 CONTRIBUTING.md                 # Contributing guide

File Count & Statistics

By Type

• Python files: 25+
• Configuration files: 10+
• Documentation files: 10+
• Docker files: 3
• Script files: 3
• Configuration/Data files: 15+

By Category

Core Application (app/)

Total: 18 Python files
├── Main modules: 3 (main, settings, db)
├── Models: 8 (base + 7 specific models)
├── Handlers: 8 (commands, callbacks, messages, etc)
├── Celery: 2 (config, tasks)
└── Scheduling: 1 (scheduler)

Infrastructure (Docker/K8s)

Total: 6 files
├── Dockerfile: 1
├── Docker Compose: 2 (dev + prod)
├── .dockerignore: 1
└── K8s templates: 2 (optional)

CI/CD & Automation

Total: 5 files
├── GitHub Actions workflows: 2
├── Pre-commit hooks: 1
├── Renovate config: 1
└── Make/Bash scripts: 3

Documentation

Total: 10+ files
├── Main docs: 4
├── Guides: 6+
└── Examples: Multiple

Configuration

Total: 8 files
├── .env templates: 1
├── .gitignore: 1
├── Project config: 1 (pyproject.toml)
├── Pre-commit config: 1
├── Renovate config: 1
└── Alembic config: 1

Key Files Reference

🎯 Getting Started

1. README.md - Start here
2. DEVELOPMENT.md - Local setup
3. quickstart.sh - Automated setup

🏗️ Architecture & Understanding

1. docs/DOCKER_CELERY.md - Architecture details
2. PRODUCTION_DEPLOYMENT.md - Production architecture
3. docs/ARCHITECTURE.md - System design

🚀 Deployment

1. docker-compose.yml - Development
2. docker-compose.prod.yml - Production
3. PRODUCTION_DEPLOYMENT.md - Deployment guide
4. docker.sh - Management script

📦 Dependencies & Config

1. requirements.txt - Production packages
2. requirements-dev.txt - Development packages
3. pyproject.toml - Project metadata
4. .env.example - Environment template

🧪 Testing & Quality

1. .github/workflows/tests.yml - Test pipeline
2. .github/workflows/docker.yml - Build pipeline
3. .pre-commit-config.yaml - Code quality
4. pyproject.toml - Tool configuration

🔧 Development Tools

1. Makefile - Command shortcuts
2. docker.sh - Docker management
3. quickstart.sh - Setup automation

File Purposes Summary

Application Core

File	Purpose	Lines
app/main.py	Bot initialization & startup	~100
app/settings.py	Configuration management	~150
app/db.py	Database setup & sessions	~80
app/celery_config.py	Celery initialization	~45
app/celery_tasks.py	Task definitions	~250
app/scheduler.py	Job scheduling	~200

Models (ORM)

File	Purpose	Lines
app/models/base.py	Base model class	~30
app/models/group.py	Group entity	~50
app/models/message.py	Message entity	~50
app/models/message_group.py	Many-to-many rel	~40
app/models/group_member.py	Member tracking	~45
app/models/group_keyword.py	Keyword filtering	~35
app/models/group_statistics.py	Stats aggregation	~40

Handlers (Bot Logic)

File	Purpose	Lines
app/handlers/commands.py	/start, /help, /create	~150
app/handlers/callbacks.py	Button callbacks	~120
app/handlers/messages.py	Text message handling	~80
app/handlers/telethon_client.py	Telethon client mgmt	~200
app/handlers/hybrid_sender.py	Send logic	~100
app/handlers/group_parser.py	Member parsing	~120
app/handlers/group_manager.py	Group management	~100
app/handlers/schedule.py	Schedule commands	~130

Infrastructure

File	Purpose	Lines
Dockerfile	Container image	~30
docker-compose.yml	Dev environment	~250
docker-compose.prod.yml	Prod environment	~350
.dockerignore	Build exclusions	~30
.github/workflows/docker.yml	Build/push pipeline	~100
.github/workflows/tests.yml	Test pipeline	~120

Automation & Config

File	Purpose	Lines
docker.sh	Docker management	~180
Makefile	Make targets	~120
quickstart.sh	Setup automation	~100
pyproject.toml	Project metadata	~150
.pre-commit-config.yaml	Code quality hooks	~60
renovate.json	Dependency updates	~50

Documentation

File	Purpose	Lines
README.md	Project overview	~400
DEVELOPMENT.md	Dev guide	~400
PRODUCTION_DEPLOYMENT.md	Deploy guide	~700
docs/DOCKER_CELERY.md	Docker/Celery guide	~500
docs/DOCKER_QUICKSTART.md	Quick reference	~100
docs/DOCKER_CELERY_SUMMARY.md	Feature summary	~200
IMPROVEMENTS_SUMMARY.md	Changes overview	~300

Dependencies Management

Production Dependencies (requirements.txt)

• Telegram: pyrogram, telethon
• Database: sqlalchemy, asyncpg, psycopg2-binary
• Queue/Cache: celery, redis
• Scheduling: APScheduler, croniter
• Web/Async: aiofiles, python-dateutil
• Config: pydantic, python-dotenv

Development Dependencies (requirements-dev.txt)

• Testing: pytest, pytest-cov, pytest-asyncio, pytest-watch
• Code Quality: black, flake8, isort, mypy, pylint, bandit
• Development: ipython, ipdb, watchdog
• Documentation: sphinx, sphinx-rtd-theme
• Debugging: debugpy

Database Schema Files

Migration Files (migrations/versions/)

• Initial schema (Groups, Messages, etc)
• Add group members tracking
• Add statistics tables
• Add keyword filtering
• (+ 5-10 more migrations as needed)

Each migration is tracked by Alembic for version control.

Configuration Files Explained

.env.example

Template for environment variables needed for:

• Telegram credentials
• Database connection
• Redis connection
• Logging configuration
• Celery settings

pyproject.toml

Modern Python project configuration including:

• Package metadata
• Dependencies (main & optional)
• Tool configurations (black, isort, mypy, pytest, etc)
• Build system settings

.pre-commit-config.yaml

Automated code quality checks before git commit:

• Code formatting (black, isort)
• Linting (flake8, mypy, pylint)
• Security (bandit)
• General (trailing whitespace, merge conflicts)

Workflow Integration

Development Workflow

Edit Code → Pre-commit hooks → Commit → GitHub Actions (tests)

Build Workflow

Push to main → GitHub Actions (build) → Docker Hub

Deployment Workflow

docker-compose up → alembic migrate → bot ready

Best Practices Implemented

✅ Code Organization

• Clear separation of concerns
• Models, handlers, tasks separated
• Reusable components

✅ Configuration

• Environment-based config
• No secrets in code
• .env.example as template

✅ Testing & Quality

• Unit tests included
• Integration tests
• Code coverage tracking
• Linting enforcement

✅ Documentation

• README with badges
• Development guide
• Production deployment guide
• Architecture documentation
• Inline code comments

✅ Automation

• Docker containerization
• CI/CD pipelines
• Pre-commit hooks
• Dependency updates (Renovate)
• Helper scripts

✅ Security

• Secrets management
• Input validation
• SQL injection protection
• Password hashing
• HTTPS support

---

Total Project Files: 50+
Total Lines of Code: 2000+
Total Lines of Documentation: 2000+
Overall Complexity: Production-Grade ✅