🎓 SYJ EDUCATE

An open-source engineering education engine — real, tested, working code instead of isolated tutorials.

Eight learning tracks. Three full applied examples. 151 passing tests. Zero mockups.

Every claim on this page is backed by a real test run or a real live demo — not marketing copy. See Verification Philosophy below.

Quick Start • Features • Architecture • Tracks • Applied Examples • Termux / Android • Roadmap

🎬 See It Run

Every clip below is a genuine recording of real commands against real, running code in this repository — captured while building it, not staged afterward.

DNS reconnaissance, live, against a real domain
_{The osint/ track resolving real records in real time — no mocked responses.}

The full test suite, run fresh
_{151 tests across 8 tracks passing from a clean install — no cached state.}

A real recorded uptime incident
_{The automation/ track catching and logging a genuine HTTP failure — not a fabricated demo.}

Sales pipeline reporting, hand-verified
_{The small-business-crm/ example's win-rate math, checked against the source data.}

✨ Key Features

🧩 Eight complete learning tracks — backend, database, frontend, AI, security, OSINT, automation, and applied examples, each buildable and testable in isolation
✅ 151 passing tests, verified from a clean install — no cached state, no "works on my machine"
🖥️ Live-verified, not just unit-tested — real servers started, real HTTP requests sent, real responses checked against real domains and real endpoints
🐛 Real bugs, documented in the open — a path-traversal exploit, an operator-precedence bug, a broken test-isolation hook — each written up with cause and fix, not swept under the rug
🤖 Local-first AI — Ollama, Qwen, and DeepSeek by default; no dependency on closed-source APIs
📱 Termux / Android-aware — dependency choices and setup docs account for constrained mobile environments from day one
🏭 Three full applied examples — restaurant ordering, livestock tracking, and a small-business CRM, each combining multiple tracks into one working product
🔓 MIT licensed — fork it, teach with it, ship it

🎯 Why This Repository Is Different

Most example repositories show code that looks correct. This one is held to a stricter bar:

Every track has a real test suite that passes from a fresh install, not just in one developer's already-configured environment.
Most tracks were also live-verified, not just unit-tested: a real backend server started, real HTTP requests sent, real responses checked by hand against expected values.
Real bugs were found and documented, not hidden. A path-traversal vulnerability in a file-upload endpoint. A Python operator-precedence bug that silently dropped a function argument. A FastAPI startup hook that broke test isolation. Each is written up — what it was, how it was caught, how it was fixed — in the relevant track's docs/ARCHITECTURE.md or security/reviews/.
Limitations are stated, not glossed over. Where something wasn't (or couldn't be) fully verified in the environment this was built in — WHOIS lookups needing a network port that's often firewalled, PostgreSQL not being available to test against everywhere — that's written down explicitly instead of implied to work.

🏗️ Architecture

The diagrams below are pattern/lineage maps, not literal shared code — livestock-tracker/ and small-business-crm/, for example, reuse the patterns backend/ and database/ establish, implemented independently, not by importing those tracks' code.

Applied Example Request Flow

The pattern every applied example (restaurant-ordering/, livestock-tracker/, small-business-crm/) follows, end to end:

flowchart TD
    A["Client<br/>Browser / Mobile"] -->|HTTP Request| B["FastAPI Backend"]
    B --> C{"Authenticated<br/>Route?"}
    C -->|Yes| D["JWT Verification"]
    C -->|No| E["Public Handler"]
    D --> F["Business Logic<br/>State Machine + Validation"]
    E --> F
    F --> G[("SQLite / PostgreSQL<br/>via SQLAlchemy")]
    G --> F
    F --> H["JSON Response"]
    H --> A

Component Overview

How a single track — client, runtime, and storage — fits together:

flowchart TB
    subgraph Client["🖥️ Client"]
        A["Vanilla JS Frontend<br/>Fetch API, no build step"]
    end
    subgraph Runtime["⚙️ Runtime"]
        B["FastAPI App<br/>app/main.py"]
        C["SQLAlchemy Models<br/>app/models.py"]
        D["Alembic Migrations"]
    end
    subgraph Storage["💾 Storage"]
        E[("SQLite (dev)<br/>PostgreSQL (prod)")]
    end
    A -->|"REST / JSON"| B
    B --> C
    C --> E
    D --> E

Tracks → Applied Examples

How the eight standalone tracks combine to produce the three full applications (a track box with no arrow out — ai, security, osint, automation — is a complete, independently runnable track that simply hasn't been folded into an applied example yet):

flowchart LR
    subgraph Tracks
        T1["backend"]
        T2["database"]
        T3["frontend"]
        T4["ai"]
        T5["security"]
        T6["osint"]
        T7["automation"]
    end
    subgraph Examples["Applied Examples"]
        E1["restaurant-ordering"]
        E2["livestock-tracker"]
        E3["small-business-crm"]
    end
    T1 --> E1
    T2 --> E1
    T3 --> E1
    T1 --> E2
    T2 --> E2
    T1 --> E3
    T2 --> E3

📚 Learning Tracks

Track	Focus	Tests	Status
`backend/`	Python, FastAPI, JWT auth, REST APIs, async, middleware	28	✅
`database/`	SQLAlchemy 2.0, real Alembic migrations, indexing, SQLite → PostgreSQL	10	✅
`frontend/`	Vanilla HTML/CSS/JS, Fetch API, responsive design, PWA offline shell	—	✅
`ai/`	Local AI via Ollama, RAG pipeline, no proprietary API dependency	11	✅
`security/`	OWASP-style review of `backend/`, threat modeling, secrets management	—	✅
`osint/`	DNS/WHOIS/subdomain recon, email spoofing analysis — defensive use only	23	✅
`automation/`	URL uptime monitoring: web automation, scheduling, reporting	16	✅
`examples/`	Industry-inspired full applications combining the tracks above	63	✅

🏭 Applied Examples

Real, multi-part applications that combine several tracks against one domain:

Example	Industry	Demonstrates	Tests
`restaurant-ordering/`	Restaurants / Cloud Kitchens	Public + authenticated access on one API, an order-status state machine, CORS, full frontend	21
`livestock-tracker/`	Agriculture	Cumulative-constraint validation, real feed-conversion-ratio math	20
`small-business-crm/`	Small Business / SaaS	A validated sales-pipeline state machine, win-rate and time-to-close reporting	22

🗂️ Repository Structure

syj-educate/
├── ai/                        Local AI (Ollama) + RAG — FastAPI, 11 tests
├── backend/                   JWT-auth REST API — FastAPI + SQLite, 28 tests
├── database/                  SQLAlchemy ORM + real Alembic migrations, 10 tests
├── frontend/                  Vanilla JS + PWA, consumes backend/
├── security/                  OWASP review of backend/, threat model, secrets tools
├── osint/                     DNS/WHOIS/subdomain/email analysis, 23 tests
├── automation/                Site Watch: uptime monitor + scheduler, 16 tests
├── examples/
│   ├── restaurant-ordering/   backend + database + frontend together, 21 tests
│   ├── livestock-tracker/     Agriculture batch tracking, 20 tests
│   └── small-business-crm/    Sales pipeline CRM, 22 tests
├── docs/
│   └── ROADMAP.md             Build history and what's next
├── assets/                    Demo GIFs (this README's screenshots)
├── setup.sh                   Base environment bootstrap
└── LICENSE                    MIT

Every track is self-contained — its own requirements.txt, virtual environment, and tests. There's no single shared dependency list to keep in sync; that's a deliberate choice, documented in each track's docs/ARCHITECTURE.md.

🚀 Quick Start

Prerequisites

Requirement	Needed For	Check
Python 3.9+	Every track	`python3 --version`
`pip` + `venv`	Every track	`python3 -m venv --help`
Git	Cloning the repo	`git --version`
Ollama	`ai/` track only	`ollama --version`
Node.js (optional)	Nothing — all frontends are build-step-free	`node --version`

If python3 -m venv --help fails on Debian/Ubuntu, install it first: sudo apt install python3-venv. On Termux, see the dedicated section below before you start.

1. Clone and bootstrap

git clone https://github.com/SHalimoosavi/syj-educate.git
cd syj-educate
./setup.sh

setup.sh checks for a working Python 3.9+ toolchain, creates a base virtual environment, and installs shared dev tooling (pytest, black, ruff). It does not install every track's dependencies — each track manages its own, so you only install what you're actually going to run.

2. Pick a track and follow its own quick start

Expand whichever track you want to run:

🔧 backend/ — JWT-authenticated REST API

cd backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

# Generate a real secret key instead of using the placeholder:
python3 -c "import secrets; print(secrets.token_hex(32))"
# → paste the result into .env as SECRET_KEY=...

.venv/bin/uvicorn app.main:app --reload
# API docs: http://localhost:8000/docs

📖 Full guide: backend/docs/SETUP.md

🗄️ database/ — SQLAlchemy + real Alembic migrations

cd database
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
.venv/bin/alembic upgrade head
.venv/bin/python -m scripts.seed

📖 Full guide: database/docs/SETUP.md

🌐 frontend/ — consumes backend/, no build step

# Terminal 1 — start backend/ first (see above)

# Terminal 2
cd frontend
python3 -m http.server 8080
# Open http://localhost:8080/index.html

📖 Full guide: frontend/docs/SETUP.md

🤖 ai/ — local AI with Ollama + RAG

# Install Ollama separately, then:
ollama serve
ollama pull qwen2.5:7b
ollama pull nomic-embed-text

cd ai
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m scripts.ingest
.venv/bin/uvicorn app.main:app --reload

📖 Full guide: ai/docs/SETUP.md

🕵️ osint/ — DNS, WHOIS, subdomain, and email analysis

⚠️ Read osint/docs/ETHICS.md first — every tool here is for domains and infrastructure you own or are authorized to assess.

cd osint
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

.venv/bin/python cli.py dns yourdomain.com
.venv/bin/python cli.py email fixtures/sample_suspicious.eml

📖 Full guide: osint/docs/SETUP.md

📡 automation/ — Site Watch (URL uptime monitor)

cd automation
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python cli.py check-all urls.example.txt
.venv/bin/python cli.py report

📖 Full guide: automation/docs/SETUP.md

🍽️ examples/restaurant-ordering/ — full-stack applied example

cd examples/restaurant-ordering/backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/alembic upgrade head
.venv/bin/python -m scripts.seed
.venv/bin/uvicorn app.main:app --reload

# Second terminal:
cd examples/restaurant-ordering/frontend
python3 -m http.server 8080
# Customer view: http://localhost:8080/customer.html
# Staff/kitchen view: http://localhost:8080/staff.html (admin / changeme123)

📖 Full guide: examples/restaurant-ordering/README.md

🐄 examples/livestock-tracker/ & 📈 examples/small-business-crm/

Same pattern for both:

cd examples/livestock-tracker   # or examples/small-business-crm
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m scripts.init_db
.venv/bin/uvicorn app.main:app --reload

📖 Guides: livestock-tracker/docs/SETUP.md · small-business-crm/docs/SETUP.md

Troubleshooting

Problem	Likely Cause	Fix
`python3: command not found`	Python isn't installed, or is aliased to `python`	Try `python --version`; if that works, use `python` in place of `python3` throughout
`ModuleNotFoundError` after install	The virtual environment isn't activated, or the wrong one is	Confirm you're running `.venv/bin/python`/`.venv/bin/pip`, not a global install
`Address already in use` on port 8000/8080	Another process (maybe a previous run) is still bound to it	Stop the old process, or run with `--port 8001` and adjust the URL you open
`pip install` fails building a C extension	Missing build tools (common on Termux/minimal Linux)	Install a compiler toolchain (`pkg install clang make` on Termux, `apt install build-essential` on Debian/Ubuntu) — see Termux notes
CORS error in the browser console (frontend tracks)	The backend's `CORS_ORIGINS` doesn't include the origin you're serving the frontend from	Check that track's `.env` — defaults match the exact commands in this README

🧪 Running the Tests

Every track follows the same pattern:

cd <track-directory>
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m pytest -v

📱 Running on Termux (Android)

This project is developed with constrained mobile environments in mind — SQLite over a heavier database, raw Python over native-extension-heavy libraries where reasonable, and dependency-injected clients throughout are partly a reflection of that. A few things to know if you're running this on Termux:

Base tools — pkg install python git gets you Python 3, pip, and venv. If any dependency needs to compile a C extension, also run pkg install clang make.
uvicorn[standard] — the [standard] extra pulls in uvloop and httptools, both C extensions without reliable prebuilt Termux wheels. If installation stalls or fails, drop the extra: pip install uvicorn. It falls back to the pure-Python asyncio loop, which works fine for local development.
database/'s PostgreSQL path — psycopg[binary] may not have a prebuilt Termux wheel either. The pure-Python pg8000 driver is a drop-in alternative for testing the Postgres connection string; the SQLite path (the default) needs nothing special.
Alembic, SQLAlchemy, FastAPI, Pydantic, httpx, dnspython — all pure Python or ship broad wheel support, so these install without issue.
Frontends — deliberately framework-free with no build step, so Node/npm isn't required to run them; Python's own http.server is enough. pkg install nodejs works if you want Node for something else.
Long-running processes — automation/'s watch command (or any dev server) can get suspended when Termux loses foreground focus. Run termux-wake-lock first, or prefer the check-all + Termux:Boot/cron pattern in automation/docs/SETUP.md for background use.
Networking — binding to localhost/127.0.0.1 on ports 8000/8080 works the same as anywhere else; no Termux-specific networking setup needed.

None of this is guaranteed for every Termux version or device — if something above is out of date, please open an issue with what you found.

🔒 Security

The backend/ track went through a dedicated OWASP-style review: 13 findings, 7 fixed in code — including a genuinely exploitable path-traversal vulnerability in a file-upload endpoint, found by reading the code and confirmed fixed by actually attempting the exploit against a live running server, not just asserting on a mock.

📄 Full writeup: security/reviews/backend-security-review.md
🧭 Threat model: security/threat-models/backend-threat-model.md
🔑 Secrets management tools + working examples: security/secrets-management/

If you find a security issue in this repository, please open an issue describing it. This is a learning project, not a monitored production service, so there's no formal disclosure program — but reports are genuinely welcome.

🧠 AI Philosophy

AI features in this project default to open-source, locally runnable models — Ollama, Qwen, DeepSeek — rather than closed-source APIs. Where a proprietary API would normally be used, an open-source alternative is documented alongside it instead.

🗺️ Roadmap

See docs/ROADMAP.md for build history, what's implemented, and what's planned next — currently: further applied examples covering logistics, retail, healthcare intake, and education.

🤝 Contributing

Issues and pull requests are welcome. If you're adding a track or applied example, the established pattern is:

✅ Real tests
📄 A docs/ARCHITECTURE.md explaining why each non-obvious decision was made
🔬 Verification against a real running instance where practical, not just mocks

Look at any existing track's docs/ folder for the shape this takes.

📄 License

MIT — see LICENSE.

👤 Author

Syed Ali Hasan Moosavi (@SHalimoosavi)

Founder & Managing Director, Sayanjali Nexus Private Limited

🌐 Portfolio: shalimoosavi.github.io/moosavi

Navigation Menu

Repository files navigation

🎓 SYJ EDUCATE

An open-source engineering education engine — real, tested, working code instead of isolated tutorials.

🎬 See It Run

✨ Key Features

🎯 Why This Repository Is Different

🏗️ Architecture

Applied Example Request Flow

Component Overview

Tracks → Applied Examples

📚 Learning Tracks

🏭 Applied Examples

🗂️ Repository Structure

🚀 Quick Start

Prerequisites

1. Clone and bootstrap

2. Pick a track and follow its own quick start

Troubleshooting

🧪 Running the Tests

📱 Running on Termux (Android)

🔒 Security

🧠 AI Philosophy

🗺️ Roadmap

🤝 Contributing

📄 License

👤 Author

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
ai		ai
assets		assets
automation		automation
backend		backend
database		database
docs		docs
examples		examples
frontend		frontend
osint		osint
scripts		scripts
security		security
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

🎓 SYJ EDUCATE

An open-source engineering education engine — real, tested, working code instead of isolated tutorials.

🎬 See It Run

✨ Key Features

🎯 Why This Repository Is Different

🏗️ Architecture

Applied Example Request Flow

Component Overview

Tracks → Applied Examples

📚 Learning Tracks

🏭 Applied Examples

🗂️ Repository Structure

🚀 Quick Start

Prerequisites

1. Clone and bootstrap

2. Pick a track and follow its own quick start

Troubleshooting

🧪 Running the Tests

📱 Running on Termux (Android)

🔒 Security

🧠 AI Philosophy

🗺️ Roadmap

🤝 Contributing

📄 License

👤 Author

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages