NokosBotPrimary

Sanitized public showcase of a Telegram-based digital account inventory and order automation system.

This repository is not a raw production dump. It is a cleaned engineering case study prepared for portfolio and recruiter review. Real bot tokens, private session files, payment payloads, operator identities, and sensitive business data were removed before publication.

Why this repository matters

This project is valuable because it shows more than a simple bot.

It demonstrates how a real workflow system coordinates:

• chat-driven user interaction
• MySQL-backed inventory and order state
• deposit verification and balance updates
• OTP and session-assisted account handover
• completion-triggered cleanup and logout
• operator-side support tooling around stock and reporting

The main engineering value is the stateful workflow design behind purchase, validation, delivery, OTP continuation, and controlled completion.

Visual overview

System architecture

Order lifecycle

Main showcase story

• main.py
  • primary customer bot
  • menu flow, deposit flow, purchase flow, order flow, and admin callbacks
• main_support.py
  • extracted states, keyboards, and shared UI/helper logic from the main bot runtime
• main2.py
  • supplier intake and stock-submission bot
• database.py
  • thin public wrapper that preserves from database import db
• database_mixins.py
  • split MySQL business logic grouped into smaller mixin domains for readability
• nokos_helper.py
  • session, OTP, spam-check, and account security helpers
• qris_helper.py
  • QRIS payload generation helper for invoice creation
• schema.sql
  • database schema reference
• tools/
  • grouped operator-side utilities such as stock import, finance reporting, moderation cleanup, and session conversion helpers

Engineering highlights

1. Validation-heavy transaction flow

The purchase path does not jump directly from click to delivery. It validates stock, computes price at the moment of purchase, updates balance, records order state, and only then continues to the next stage.

2. Stateful order completion

An order is not considered done just because account data was sent. The system still supports OTP retrieval, login continuation, and explicit completion that triggers cleanup behavior.

3. Real operational scope

This case study includes the broader surrounding system, not only the customer bot:

• supplier intake
• stock processing utilities
• reporting helpers
• moderation/cleanup helpers
• payment payload generation

4. Refactor-aware public publishing

The public version was deliberately reshaped so GitHub visitors can understand the project faster:

• secrets removed from code path
• core modules kept visible at the root
• noisy utilities grouped into tools/
• monolithic DB logic split into database_mixins.py
• main bot support logic extracted into main_support.py

Why it is relevant to QA-minded reviewers

Although this project is primarily a backend automation case study, it also reflects a strong QA mindset:

• many steps have explicit pass/fail gates
• multiple integration points must stay consistent
• order state transitions must remain valid from start to finish
• negative paths matter, not only the happy path
• completion is verified through downstream effects, not only UI feedback

That makes this repository useful evidence for roles involving backend reliability, workflow automation, integration testing mindset, and operational correctness.

Reading guide

If you only have a few minutes, use this order:

1. README.md
2. docs/ARCHITECTURE.md
3. docs/FLOWS.md
4. docs/REPO_MAP.md
5. main.py
6. main_support.py
7. database.py
8. database_mixins.py

Documentation map

• Architecture overview
• Workflow breakdown
• Repository map
• Showcase audit
• Next cleanup opportunities
• Tooling notes

Tech stack

• Python
• Aiogram
• Aiohttp
• MySQL / mysql-connector-python
• Pyrogram
• Telethon
• QRIS / payment payload helper logic
• VPS-style operational tooling and script-driven workflows

Public showcase boundary

This public repo intentionally excludes:

• real Telegram bot tokens
• real Telegram API credentials
• real session files
• private payment payloads and operator-specific secrets
• live business data and production-only artifacts

If a flow looks simplified or placeholder-based in config, that is intentional for safe publication.

Local run notes

This repository is intended first as a showcase and engineering sample. If you want to run it privately for study:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Then fill .env with your own private credentials and prepare MySQL using schema.sql.

What remains imperfect on purpose

This repo is much cleaner than the original source drop, but it is still honest about its origin as a real evolving system.

Remaining technical debt worth improving in later passes:

• split main.py handlers more aggressively into domain-specific modules
• break database_mixins.py into separate files by domain if the repo grows again
• add automated tests around deposit approval, purchase locking, and completion flow
• add blurred or redacted UI screenshots from the portfolio deck for richer repo presentation

Showcase intent

This repository supports my portfolio and CV as evidence of practical experience in:

• backend workflow automation
• Telegram bot engineering
• database-backed transactional flows
• validation-heavy business logic
• session and OTP support workflows
• operational services that must stay reliable under real usage