🎓 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.

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 Highlights 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.

💡 Recording your own demos? Drop new .gif files into assets/ and reference them the same way — docs/ROADMAP.md tracks which tracks still need a recorded walkthrough (currently: automation/'s live uptime incident, and the small-business-crm/ pipeline demo).

---

✨ 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
• 🤖 Local-first AI — Ollama, Qwen, and DeepSeek by default; no dependency on closed-source APIs
• 📱 Termux / Android-native — built and tested 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

---

🏗️ Architecture

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

Loading

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

Loading

Tracks → Applied Examples

How the eight standalone tracks combine to produce the three full applications:

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

Loading

---

📚 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

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. Pick a track below and follow its own quick start.

🔧 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

---

🧪 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

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:

1. ✅ Real tests
2. 📄 A docs/ARCHITECTURE.md explaining why each non-obvious decision was made
3. 🔬 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