Project Structure — Folders Aur...

Turn this lesson into one checked practice output

By the end, you should be able to explain the core idea behind “Project Structure — Folders Aur Files Ka Blueprint” in your own words, apply it to one small real or sample task, and identify what still needs human review.

Learn

Read the 25-minute lesson without copying an output blindly.

Try

Use a small, non-sensitive example that you can inspect line by line.

Review

Check facts, fit, and risk; save one improvement note for next time.

A professional research bot is easier to audit when each folder has one responsibility. Network retrieval, normalization, research features, paper fills, storage, reporting, and tests must not blur together. The strongest safety control is structural: the repository contains no module capable of authenticating to a venue or transmitting an order.

Use this blueprint:

paper_bot/
  pyproject.toml
  README.md
  SAFETY.md
  config/default.yaml
  data/raw/  data/normalized/  data/fixtures/
  src/paperbot/config.py
  src/paperbot/data/fetch.py
  src/paperbot/data/normalize.py
  src/paperbot/research/features.py
  src/paperbot/paper/fills.py
  src/paperbot/storage/events.py
  src/paperbot/reporting/dashboard.py
  tests/unit/  tests/integration/  tests/fixtures/

Dependencies should point inward. Reporting may read stored events; storage must not import reporting. Paper fills may consume validated research records; the data adapter must know nothing about fills. This prevents a “convenient” function from quietly reaching across boundaries.

Define narrow typed objects at layer edges. RawSnapshot carries bytes, capture time, host, status, and hash. NormalizedMarket carries validated fields plus provenance. PaperDecision carries hypothesis version, evidence IDs, abstention reason, and synthetic point limit. No object contains a token, private key, account balance, or destination address.

Keep configuration separate from code, but do not make every behavior configurable. Safety invariants are constants: EXECUTION_MODE = "PAPER_ONLY", permitted schemes are HTTPS, and permitted operations are GET. A YAML edit must never activate a live path. If a requested setting conflicts with an invariant, startup exits with a clear error.

Definition of done per layer

Each package needs a public interface, input validation, structured errors, unit tests, and a short README. Tests should run on fixtures with the network disabled. Integration tests may start a local fake server to exercise timeouts and malformed responses. The main command composes layers; it does not implement their details.

🇵🇰 Pakistan Angle

Many learners work on shared family machines or budget laptops. A plain Python package, SQLite file, and static report keep the architecture portable. Store only public records and fictional paper events. Do not put CNICs, phone numbers, personal messages, or client data in fixtures, screenshots, or Git history.

Hands-On Exercise

Create the skeleton and an import-boundary test. Add placeholder protocols for MarketDataReader, PaperFillEngine, and EventStore. Run a repository search for private_key, seed, wallet, place_order, and cancel_order; the result must be empty except the safety test that lists forbidden terms.

Completion Rubric

Folder responsibilities and dependency direction are documented.
Edge objects include provenance and exclude credentials.
Paper-only behavior is an invariant, not a YAML switch.
Tests run from synthetic/versioned fixtures without internet.
A forbidden-capability scan is automated.

Sources

Key takeaway: The safest paper bot is a set of narrow research components with no execution capability anywhere in its dependency graph.

Before you mark Lesson 2.1 complete

Can I explain “Project Structure — Folders Aur Files Ka Blueprint” without reading the lesson back word for word?

Did I complete the lesson’s practice step on a real or clearly labelled sample task?

Did I check the result for invented facts, private data, unsafe actions, and mismatch with the brief?