Project documentation & architecture — documentation-only repository (no application source)
Other language: العربية — README.ar.md
This is an operator-grade Snapchat automation platform—not a single script. It is built for people who need repeatable production: many accounts, many browsers, and fewer stop-the-world failures when the app changes, the network wobbles, or verification providers act up.
What you get in one coherent system
- Account factory: End-to-end signup with phone or email paths, centralized configuration from your backend, and clean hand-off of cookies/sessions and metadata to storage or your API.
- Follow engine: Target lists, progress tracking, logging, and the same hardened browser layer used for signup—so growth work does not feel like a separate, fragile project.
- Story & feed engagement (operational layer): Flows are designed so accounts can open stories and consume timeline content in a controlled way—useful for warming, realism, and keeping sessions “alive” compared to create-only bots that never behave like real users.
- Connections & “fresh app” behavior: Periodic restarts, session preservation helpers, and backend-driven modes help the fleet stay aligned with the latest app flows instead of freezing on an old assumption.
- Risk-aware operation (not magic): Isolated profiles, proxy/VPN extension hooks, stealth-oriented automation, and human-like pacing are there to reduce suspicious patterns and recover faster from soft limits or session glitches—you still must comply with laws and Snapchat’s terms.
Problem handling you actually feel in production
- Popup and dialog storms, flaky pages, and partial loads are handled with shared page utilities and defensive waits—not one-off hacks per account.
- SMS balance and provider edge cases can be detected and surfaced so the fleet does not spin forever on a dead path.
- Fatal safety: On critical failures, profiles can be stopped in bulk so machines do not leak hundreds of hung browsers.
- Backups & remote control: Heartbeats, optional artifact upload, and script modes mean your backend remains the brain while workers stay disposable.
Licensing: The full product (source, binaries, onboarding) is not in this public documentation repo. Use the contact section to discuss purchase, deployment, and support from Storage TE.
This repository describes a professional automation system focused on Snapchat account creation and related workflows. The design centers on:
- Orchestrated browser automation (managed isolated profiles, stealth-oriented connection, session handling).
- Verification pipelines (phone/SMS providers and email flows, configurable from a central backend).
- Remote control & observability (script modes, heartbeats, backups, optional release/update channel).
- Optional follow / engagement modules that reuse the same browser stack and safety patterns.
- Resilience (hourly restart flags, fatal-error cleanup, memory and session stability helpers).
Repository policy: This GitHub project is intentionally documentation-only. It explains architecture, data flow, and operational model without publishing proprietary source code. Clone or mirror the real codebase separately under your own access policy.
This documentation does not discuss commercial pricing or subscription costs of third-party browser-profile or antidetect tooling—only integration concepts (local API, profile lifecycle: create → start → stop → delete).
flowchart TB
subgraph Control["Control plane"]
RUN["run.js — mode polling & lifecycle"]
LAUNCH["launcher.js — local restart & deps"]
PM2["Optional: PM2 / process supervisor"]
end
subgraph Backend["Backend services"]
API["REST API — modes, SMS config, heartbeat, backup, releases"]
end
subgraph Workers["Worker processes"]
CREATE["Account creation pipeline"]
FOLLOW["Follow / targets module"]
end
subgraph Browser["Browser layer"]
PROF["Profile manager API — isolated profiles"]
PUP["Puppeteer + stealth plugins"]
EXT["Extensions: VPN / captcha helpers"]
end
subgraph External["External integrations"]
SMS["SMS / virtual number APIs"]
MAIL["IMAP / email verification"]
S3["Object storage — profile artifacts"]
end
RUN --> API
RUN --> CREATE
RUN --> FOLLOW
LAUNCH --> RUN
PM2 --> RUN
CREATE --> PROF
CREATE --> PUP
FOLLOW --> PROF
FOLLOW --> PUP
PUP --> EXT
CREATE --> SMS
CREATE --> MAIL
CREATE --> S3
FOLLOW --> API
How to read this diagram: The control plane never drives the browser directly—it only chooses which worker runs and reconciles restarts/updates. Workers are short-lived or looping Node processes that talk to the profile manager and Puppeteer. External systems are integration boundaries: you can change SMS vendor or bucket name without rewriting the Snapchat UI steps.
| Layer | Responsibility |
|---|---|
| Entry & orchestration | Single entry reads backend script mode (create_only, follow_only, create_and_follow, stop), handles restart requests, optional hourly restart, and spawns the correct worker script. |
| Account creation module | Loads identity data (names, region, gender), chooses phone vs email signup path, drives Snapchat UI steps, preserves cookies/session, pushes results to backend and/or object storage. |
| Follow module | Authenticates against targets, runs follow actions with logging and progress tracking; shares DOM/page helpers and VPN behavior with creation flow where applicable. |
| Profile manager integration | Abstract lifecycle: create profile → start → attach automation → stop/delete on failure or completion; WebSocket endpoint for Puppeteer connection. |
| Configuration | JSON/env-based settings for operators, countries, proxy mode, window layout, concurrency caps. |
| Stability | Session preservation, popup handling, human-behavior timing, fatal handlers that stop all profiles on uncaught errors. |
The orchestrator periodically asks your API which mode the fleet should run. That lets one backend steer many machines without logging into each host for every change.
| Mode | Typical use |
|---|---|
create_only |
Produce new accounts end-to-end |
follow_only |
Use existing sessions for growth / targets |
create_and_follow |
Combined pipeline (signup then follow / warm-up) |
stop |
Graceful drain; workers exit so supervisors can idle |
stateDiagram-v2
direction LR
[*] --> polling
polling --> create_only : instruction
polling --> follow_only : instruction
polling --> create_and_follow : instruction
polling --> stop : instruction
create_only --> polling : next cycle / restart
follow_only --> polling : next cycle / restart
create_and_follow --> polling : next cycle / restart
stop --> [*]
flowchart TB
subgraph Remote["Your backend (cloud or self-hosted)"]
API2["REST — modes, SMS config, releases, backups"]
DB[("Optional DB / queue")]
API2 --- DB
end
subgraph Site["Each worker host — VPS or PC"]
LAUNCH2["launcher.js"]
RUN2["run.js"]
IDX["index.js / follow-snapchat.js"]
PMGR["Profile manager (local API)"]
BR2["Chromium / isolated profiles"]
LAUNCH2 --> RUN2
RUN2 --> IDX
IDX --> PMGR
PMGR --> BR2
end
RUN2 <-->|HTTPS + token| API2
Explanation: One backend can coordinate many worker sites. Each site keeps secrets in .env and owns its browser pool; the backend holds policy (modes, targets, SMS rules) and aggregated status (heartbeats, backups).
stateDiagram-v2
[*] --> created
created --> running : start profile
running --> automating : Puppeteer connects (WebSocket)
automating --> success : signup / task OK
automating --> failure : error / timeout / no SMS balance
success --> stopped : stop profile
failure --> deleted : delete profile
stopped --> [*]
deleted --> [*]
Why it matters: Isolated profiles mean cookies, local storage, and extension state do not leak between accounts. On failure, delete avoids carrying corrupted state into the next attempt. On success, stop (without delete) may be used when the same machine continues with follow-only work—depending on your runbook.
flowchart LR
T["Targets / progress files"] --> L["Session + Snapchat UI"]
L --> N{"More targets?"}
N -->|"yes"| F["Follow + log + throttle"]
F --> S["Sync progress / backend"]
S --> N
N -->|"no"| E["Clean exit / next mode"]
This path reuses page utilities, VPN/extension context, and logging so operators see the same class of metrics as in account creation.
flowchart TB
START["Snapchat signup UI"] --> CHOICE{"Configured method?"}
CHOICE -->|"phone"| BUY["Acquire virtual number"]
BUY --> OTP["Poll SMS / enter OTP"]
OTP --> DONE["Persist session + metadata"]
CHOICE -->|"email"| BOX["Mailbox / IMAP or link flow"]
BOX --> DONE
Note: Phone flows often buy the number after the first form step (provider and economics). Email flows bind the inbox early from your prepared data source.
flowchart TB
FATAL["Uncaught exception / unhandled rejection"] --> GH["Global fatal handler"]
GH --> STOP["Stop all browser profiles"]
STOP --> EXIT["Exit process — supervisor restarts if configured"]
SOFT["Flaky selector / slow network"] --> PU["Shared page helpers + retries"]
PU --> CONT["Continue or escalate"]
Goal: A single bad page should not leave tens of hung browsers consuming RAM and profile slots. Recoverable errors stay local to the account; fatal errors drain the whole host’s profile manager view safely.
sequenceDiagram
participant O as Orchestrator
participant B as Backend API
participant P as Profile API
participant W as Worker (Puppeteer)
participant S as SMS / Email
participant St as Storage
O->>B: Poll mode + SMS config
B-->>O: create_only / combined / stop
O->>W: Spawn creation worker
W->>P: Create / start profile
P-->>W: WebSocket debugger URL
W->>W: Snapchat signup UI flow
alt Phone signup
W->>S: Purchase / poll SMS
S-->>W: OTP / status
else Email signup
W->>S: IMAP / link verification
end
W->>St: Optional artifact upload
W->>B: Push account / metadata
W->>P: Stop / cleanup profile
The sequence is one account; in production, concurrency and queues are governed by your config + backend policy. The orchestrator may spawn multiple workers over time; each worker still follows create → verify → persist → cleanup to keep hosts predictable.
flowchart TB
LOOP["run.js main loop"] --> HB["Heartbeat to backend"]
LOOP --> INSTR["Fetch script instruction + SMS config"]
INSTR --> MODE["Spawn or continue worker for mode"]
MODE --> REL{"Release update available?"}
REL -->|"yes"| EXIT["Controlled exit → apply-update → relaunch"]
REL -->|"no"| BK{"Backup interval elapsed?"}
BK -->|"yes"| UP["Upload profile snapshot + metadata"]
BK -->|"no"| HR{"Hourly restart flag?"}
UP --> LOOP
HR -->|"yes"| GRACEFUL["Graceful worker stop + profile cleanup"]
HR -->|"no"| LOOP
GRACEFUL --> LOOP
Explanation: Heartbeats prove the worker is alive. Instruction polling keeps behavior aligned with backend changes without redeploying every host manually. Backups protect against disk loss; hourly restart (optional) refreshes long-running follow jobs against stale UI state.
- Environment: Node.js (ES modules),
.envfor secrets and backend URL/token. - Process model:
run.jsas the long-lived controller;launcher.jsfor local auto-restart and dependency install when lockfile changes; optional PM2 for servers. - Updates: Backend may advertise a release artifact; exit codes can trigger apply-update scripts in a controlled rollout.
- Backups: Periodic profile snapshots uploaded with server IP and date metadata when backend is configured.
See Deployment topology and Observability & maintenance loop above for visual context.
| Estimated engineering & architecture value | USD 2,000 |
This figure reflects documented system design, integration breadth (backend control, verification, storage, resilience), and operator-grade workflow—not a retail price tag for any single third-party license. It is indicative for portfolio, licensing, or support discussions.
| Developer | Mostafa El-Bagory |
| Company | Storage TE |
| +20 100 199 5914 |
If this documentation (or the private tooling it describes) is useful to you, optional support helps maintain and improve it. Pick whatever works best for you.
| Channel | How to support |
|---|---|
| PayPal | paypal.me/sofaapi |
| Binance Pay / UID | 1138751298 — send from the Binance app (Pay / internal transfer when available). |
| Binance — deposit (web) | Deposit crypto (Binance) — sign in, pick the asset, then select BSC (BEP20). |
| BSC address (copy) | 0x94c5005229784d9b7df4e7a7a0c3b25a08fd57bc |
Network: Use BSC (BEP-20) only. This address is for USDT (BEP-20) and BTC on BSC (Binance-Peg / in-app “BTC” on BSC), matching the Binance deposit screens. Do not send native Bitcoin (on-chain BTC), ERC-20, or NFTs to this address.
Payment QR images live in assets/:
| USDT · BSC | BTC · BSC |
|---|---|
 |
 |
Operators are solely responsible for complying with applicable laws, platform terms of service, and anti-spam / privacy rules. This repository provides technical documentation only; it does not encourage abuse, credential theft, or circumvention of security measures.
- This repository (README files, Mermaid diagrams, images under
assets/, andGITHUB_METADATA.md) is shared for informational and commercial reference only. Unless an individual file states otherwise, all rights are reserved by Storage TE and the maintainer named in this document. No express license is granted to reproduce, redistribute, or build derivative marketing or training materials from this documentation without prior written permission, except where mandatory law allows (e.g. fair dealing / fair use). - Application source code, executables, production configs, credentials, and private onboarding or support bundles are not included here. Those materials remain proprietary and are available only under a separate agreement (license, statement of work, or NDA) with Storage TE.
- Third-party marks (e.g. Snapchat and related logos) belong to their respective owners. This documentation does not imply affiliation, sponsorship, or endorsement by Snap Inc. or any other platform operator.
- For licensing the product, white-label deployment, or enterprise support, use the Maintainer / contact section above.
Storage TE · storage-te.com