Project: "The Semantic Self" Life Tracker Hardware: Samsung Galaxy S5 (
klte) · PC Desktop Stack: PostmarketOS · Python · FastAPI · SQLite · Ollama (Llama3)
Installing PostmarketOS on Samsung Galaxy S5 — Master Guide
Complete step-by-step installation guide for PostmarketOS on the SM-G900F. Covers the full process from WSL environment setup to post-install configuration, including all real errors encountered during the actual installation session.
| Topic | Covered |
|---|---|
| pmbootstrap setup from GitLab (not pip) | ✅ |
Image generation with --android-recovery-zip |
✅ |
| Flash via TWRP + Odin (recommended method) | ✅ |
| Flash via Heimdall (alternative, often problematic) | ✅ |
| First SSH connection over USB and WiFi | ✅ |
| Console font fix, battery monitoring, SSH autostart | ✅ |
| 9 documented real-world errors with cause and solution | ✅ |
Project Architecture — "The Semantic Self"
High-level overview of the entire system: vision, hardware choices, the two-node distributed architecture (Collector S5 + Worker PC), data flow pipeline, full data schema, security strategy, and development roadmap.
| Topic | Covered |
|---|---|
| Privacy-first philosophy and design principles | ✅ |
| Two-node Store & Forward architecture with diagram | ✅ |
| Node A (S5): stack, responsibilities, design decisions | ✅ |
| Node B (PC): Ollama, batch processing rationale | ✅ |
| Data flow pipeline — 6-step lifecycle of a log entry | ✅ |
| Full data schema with all categories and field definitions | ✅ |
| Security strategy (Basic Auth, Cloudflare Tunnel, local DB) | ✅ |
| Development roadmap — phases 1–4 with status | ✅ |
| Android + Termux alternative approach comparison | ✅ |
Application Code & Web Interface
Detailed technical documentation of the Python codebase (logger/src/). Covers every module, function, route, and frontend template — built directly from the source code.
| Topic | Covered |
|---|---|
Directory structure of logger/ |
✅ |
.env configuration variables |
✅ |
database.py — SQLite schema, state machine, all 9 functions |
✅ |
ai_engine.py — Ollama HTTP client, prompt construction, error handling |
✅ |
server.py — all 9 FastAPI routes, auth, BackgroundTasks pattern |
✅ |
layout.html — responsive layout, colour palette, status badges |
✅ |
index.html — input form, pending queue, auto-refresh on processing |
✅ |
admin_db.html — log table, detail modal, JSON editor, syntax highlighter |
✅ |
| Troubleshooting log (nftables firewall, missing import) | ✅ |
LLM Configuration — Ollama Modelfile
Complete documentation of the custom life-tracker Ollama model: parameters, system prompt design rationale, extraction rules, full annotated JSON schema, a worked example with field-by-field annotations, and practical commands for building, testing, and debugging the model.
| Topic | Covered |
|---|---|
Ollama fundamentals (Modelfile, /api/generate, format: json) |
✅ |
temperature: 0.1 and top_p: 0.9 — technical rationale |
✅ |
| System prompt design — why each rule is phrased as it is | ✅ |
| All 6 core extraction rules with examples | ✅ |
| Full annotated JSON schema with type conventions | ✅ |
null vs false vs [] — critical semantic distinction |
✅ |
| Worked input/output example with field-by-field annotations | ✅ |
ollama create, ollama run, model update and removal |
✅ |
Integration with ai_engine.py — prompt construction, timeout |
✅ |
| 5 common extraction issues with diagnosis and fix | ✅ |
Kernel Hardware Reference — S5 on Mainline Linux
Technical reference for all hardware accessible via sysfs on the S5 running kernel 6.15.x. Includes all sysfs paths, driver names, device tree locations, and shell commands. Also documents what is not available and why.
| Topic | Covered |
|---|---|
| Battery fuel gauge (MAX17040) — all sysfs paths | ✅ |
| Charger (qcom-smbb) — why it's inactive, workarounds | ✅ |
| PMIC PMA8084 — sub-devices and SPMI base path | ✅ |
| GPIO — 4 chips, absolute numbering, export/control commands | ✅ |
| I2C buses — all 6 devices mapped with driver and function | ✅ |
| USB — ChipIdea gadget mode, RNDIS networking | ✅ |
| Thermal sensors — 10 zones mapped, read/monitor commands | ✅ |
| PMIC ADC (VADC) — IIO channels | ✅ |
| RGB LED — AN30259A, brightness control, triggers | ✅ |
| IMU / accelerometer / gyroscope — why unavailable | ✅ |
| Device tree navigation | ✅ |
Kernel config — relevant CONFIG_* symbols |
✅ |
| All commands in a single quick-reference block | ✅ |
The following files in the project root were the original working documents used as sources for the master guides above. They are kept for historical reference but should not be updated — the documents above are the authoritative versions.
| File | Content | Superseded by |
|---|---|---|
guida-postmarketos-s5.md |
Installation guide (WSL + Heimdall method) | INSTALL_POSTMARKETOS_S5.md |
guida-postmarketos-twrp.md |
Installation guide (TWRP + Odin method) | INSTALL_POSTMARKETOS_S5.md |
sessione-postmarketos-s5.md |
Live session log with errors and fixes | INSTALL_POSTMARKETOS_S5.md |
KERNEL_REFERENCE.md |
Raw sysfs reference notes | KERNEL_HARDWARE_REFERENCE.md |
GUIDA_ANDROID_SERVERS.md |
Hardware roles, Termux setup | PROJECT_ARCHITECTURE.md |
GEMINI.md |
Brief project context | PROJECT_ARCHITECTURE.md |
docs/PROJECT_DESIGN.md |
Architecture and roadmap (Italian) | PROJECT_ARCHITECTURE.md |
logger/Modelfile.md |
Ollama Modelfile | LLM_CONFIGURATION.md |
logger/docs/1_PROJECT_CONCEPT.md |
Project concept | PROJECT_ARCHITECTURE.md |
logger/docs/2_CODE_STRUCTURE.md |
Code structure notes | APPLICATION_CODE.md |
logger/docs/3_WEB_INTERFACE.md |
UI design notes | APPLICATION_CODE.md |
logger/docs/4_TROUBLESHOOTING.md |
Bug log | APPLICATION_CODE.md |
Index created: 2026-02-25