docs: comprehensive daily report with architecture overview, completion status, and handoff notes

Author: uet-santx

uet_web/Docs_software_design/daily_reports/2026-03-20.md

@@ -1,113 +1,187 @@
 # Daily Progress Report - 2026-03-20
 
-## Summary
+## Session Summary
 
-Today's work focused on making the repository safer to commit again. The main themes were Git cleanup, `uet_web` tracking repair, ignore rule cleanup, and documentation path stabilization.
+This session focused on **Git repository cleanup and stabilization**. The repository had accumulated structural problems (stuck gitlink, branch divergence, leaked build artifacts) that prevented normal commit/push. All of those have now been resolved. The repo is committed and pushed to GitHub with local and remote in sync.
 
-**Important status:** no new commit has been made for this cleanup session yet, and no push has happened yet.
+---
 
-## Completed Today
+## Part 1: System Architecture Overview
 
-### 1. Git structure cleanup
+The repository `UnityEquilibriumTheory` (uet_harness) is a **monorepo** containing multiple modules that together form a decentralized platform combining physics-based computation, blockchain, AI agents, and a web frontend.
 
-- Investigated why commit/push preparation had become difficult.
-- Confirmed that `uet_web` had been stuck in a bad Git state as a gitlink/submodule-like entry in the parent repo.
-- Backed up the old nested Git metadata for `uet_web` instead of deleting it blindly.
-- Recovered `uet_web` as a normal tracked directory in the parent repository.
-- Ran repository cleanup to reduce Git housekeeping issues.
+### Module Map
 
-### 2. File audit before commit
+| Module | Language | Purpose | Status |
+|--------|----------|---------|--------|
+| `uet_core` | Rust | Physics/math engine: master equation, fields, dynamics, calculator, parameters | **Implemented** |
+| `uet_api` | Rust (Actix) | REST API: auth, OAuth, handlers, email, MCP server, DB, agent endpoint | **Implemented** |
+| `uet_web` | TypeScript (Next.js) | Frontend: i18n (en/th/zh), auth pages, chat UI, docs viewer, workchat studio, pricing, account | **Implemented** |
+| `uet_agents` | Python | AI agent system: executive router, semantic engine, memory store (4 memory types), response composer, API server | **Implemented** |
+| `uet_chain` | Rust | Blockchain core: consensus, ledger, P2P, state, storage, canonical block logic | **Implemented** |
+| `uet_security` | Rust | Crypto: Dilithium3 (quantum-resistant), Ed25519, KeyManager, hashing, signing, envelope | **Implemented** |
+| `uet_miner` | Rust | Mining: PoUW, anti-cheat, GPU support, stratum protocol, benchmark, UET Cash block | **Implemented** |
+| `uet_kb` | Rust | Knowledge base: embeddings, document processing | **Implemented** |
+| `uet_under_development` | Rust (stubs) | Future modules: economic, governance, market, oracle | **Not started (scaffolds only)** |
+| `research_uet` | Mixed (Python/TeX/md) | Research documents, papers, Jupyter notebooks (~32,500 tracked files) | **Content exists, not code** |
 
-- Audited staged, unstaged, and untracked files.
-- Separated system-relevant files from local/generated/archive noise.
-- Identified that `uet_knowledge_state.json` is generated semantic/knowledge state and should not be committed.
-- Confirmed Rust build output like `target/` should stay ignored.
+### Infrastructure
 
-### 3. Ignore rule cleanup
+| Component | Tech | Detail |
+|-----------|------|--------|
+| Database | PostgreSQL 16 + pgvector | Vector search support, port 5433 |
+| API server | Rust/Actix | Port 3001 |
+| Web frontend | Next.js | Port 3005 (Docker) / 3000 (dev) |
+| Containerization | Docker Compose | 3 services: postgres, uet_api, uet_web |
+| ORM (web) | Prisma | Schema includes User, Wallet, Transaction, Project, Task, ComputeLog, Post |
+| Auth | JWT + OAuth (Google, GitHub) | Implemented in Rust API |
+| i18n | next-intl | English, Thai, Chinese |
 
-Updated root `.gitignore` to reduce repository bloat and accidental commits of local-only files.
+### Agent Architecture (uet_agents)
 
-Key ignored items now include:
+The agent system uses a **cognitive psychology memory model** with 4 memory types:
 
-- `/uet_history/`
-- `/uet_knowledge_state.json`
-- `.obsidian/`
-- `target/`
-- `uet_core/target/`
+1. **Working Memory** (`WorkingMemoryStore`) - current session context
+2. **Episodic Memory** (`EpisodicMemoryStore`) - conversation history with metadata
+3. **Semantic Memory** (`SemanticMemoryStore`) - persistent knowledge chunks with evidence bundles
+4. **Procedural Memory** (`ProceduralMemoryStore`) - task-type procedures
 
-Also adjusted the `uet_web/Docs_software_design` behavior so a dedicated reporting folder can be tracked while the rest can remain local-only by default.
+Flow: `ExecutiveRouter` receives a prompt -> classifies task type -> builds evidence bundle from semantic memory -> calculates equilibrium path via `UETSemanticEngine` -> generates response via `UETResponseComposer` -> stores episode.
 
-### 4. Documentation path stabilization
+The `UETSemanticEngine` uses N-gram lattice + token overlap scoring (not external embeddings) for document retrieval. Knowledge state is persisted to `uet_knowledge_state.json`.
 
-Found a docs path inconsistency in the web app:
+### Web Chat API (Multi-Agent RAG)
 
-- local docs currently exist under `uet_web/Docs_software_design/...`
-- some old Git/index references still pointed to `uet_web/docs/...`
-- the chat API was still relying on the older platform specs path
+`uet_web/src/app/api/chat/route.ts` implements a **keyword-based Multi-Agent RAG** system:
 
-Updated `uet_web/src/app/api/chat/route.ts` so it can resolve platform specs from the current `Docs_software_design/platform_specs` path first, with the old path as fallback.
+- Loads docs from `research_uet/Docs` and `Docs_software_design/platform_specs`
+- Classifies query into specialist agents: blockchain, security, economics, governance, physics, social, general
+- Searches chunks by keyword overlap
+- Synthesizes answer with source citations
 
-### 5. Reporting standard created
+---
 
-Created a reporting location for daily pre-commit reporting:
+## Part 2: What Was Done This Session (Chronological)
 
-- `uet_web/Docs_software_design/daily_reports/README.md`
+### 2.1 Git Structure Repair
 
-This folder is intended to become the standard place for daily progress reports before commits.
+**Problem:** `uet_web` was stuck as a `160000` gitlink (submodule-style entry) in the parent repo index, even though no `.gitmodules` file or nested `.git` existed. This made it impossible to `git add` any file inside `uet_web/`.
 
-## Current Repository State
+**Fix:**
+1. Ran `git rm --cached uet_web` to remove the gitlink entry
+2. Ran `git add uet_web` to re-add all files as normal tracked content
+3. The `.gitignore` rules correctly excluded `node_modules/`, `.next/`, `.env*`, and most of `Docs_software_design/`
 
-Current Git status at time of writing:
+### 2.2 Ignore Rule Cleanup
 
-- branch: `main`
-- branch relation: `ahead 32, behind 33`
-- latest visible local commit: `09cea6bde`
-- **current cleanup work is not committed yet**
-- **nothing from this cleanup/reporting round has been pushed yet**
+Updated root `.gitignore` to prevent repo bloat:
 
-There are still many repository changes present, including:
+- `target/`, `uet_core/target/` — Rust build output
+- `/uet_history/` — archived legacy docs (local only)
+- `/uet_knowledge_state.json` — generated semantic state (local only)
+- `.obsidian/` — editor metadata
+- `/uet_web/Docs_software_design/*` — local design docs (except `daily_reports/`)
+- `!/uet_web/Docs_software_design/daily_reports/` — allowed to be tracked
 
-- root config changes:
-  - `.gitignore`
-  - `Dockerfile.web`
-  - `docker-compose.yml`
-- backend/runtime changes:
-  - `uet_agents/base_agent.py`
-  - `uet_api/src/main.rs`
-  - `uet_core/src/calculator.rs`
-  - new untracked agent files under `uet_agents/`
-  - new untracked `uet_api/src/agent.rs`
-- large `uet_web` changes caused by the earlier recovery from gitlink to normal directory tracking
-- modified `uet_web/src/app/api/chat/route.ts`
+### 2.3 Docker/Prisma Build Fixes (from earlier in session history)
 
-## Risks / Open Issues
+- Switched `Dockerfile.web` from Alpine to Debian slim (SWC native dependency issue)
+- Added `DATABASE_URL` to Docker build args and runtime env
+- Made Prisma client initialization lazy to avoid build-time crashes
+- Fixed API routes (`posts`, `wallet`, `wallet/transfer`, `projects`, `compute`, `tasks`) to use lazy Prisma getter
+- Fixed schema errors: removed non-existent `role` field from User select, fixed `transactions` relation name
 
-### 1. Branch divergence remains
+### 2.4 Documentation Path Stabilization
 
-The local branch is still both ahead of and behind `origin/main`. That means GitHub sync is not solved yet. After the next local commit, pull/rebase/merge strategy still needs to be handled carefully.
+- `uet_web/src/app/api/chat/route.ts` updated to check both `Docs_software_design/platform_specs` and legacy `docs/software_design/platform_specs` paths
 
-### 2. `uet_web` commit scope is still large
+### 2.5 Daily Reporting Standard
 
-Because `uet_web` had to be repaired from bad Git tracking, Git currently sees a large amount of content there. The next commit must be reviewed carefully so that only intended work is included.
+Created `uet_web/Docs_software_design/daily_reports/` with:
+- `README.md` — standard format, naming convention (`YYYY-MM-DD.md`), required sections
+- `2026-03-20.md` — this file
 
-### 3. Documentation layout is not fully standardized yet
+### 2.6 Commit, Merge, Push
 
-The repository now has a daily reporting structure, but the broader docs layout still needs a clean final decision so that there is one clear long-term standard.
+- Committed all changes: `a23781260`
+- Merged with remote (handled rename/rename conflicts on old zip/research files, removed leaked `uet_miner/target/` build artifacts from remote history): `b7083dc8f`
+- Pushed to GitHub successfully
+- Final state: `main...origin/main` — **fully in sync, no ahead/behind**
 
-## Recommended Next Actions
+---
 
-1. Review the final intended commit scope.
-2. Keep local-only docs/history/generated files out of the commit.
-3. Write or update the daily report before each commit.
-4. Create the next commit only after the scope is confirmed.
-5. Handle branch divergence before pushing to GitHub.
+## Part 3: Development Phase History (from Git Log)
 
-## Pre-Commit Decision
+| Commit | Phase | What |
+|--------|-------|------|
+| `0520af18a` | Docs | Master architecture, database schema, docs reorganization |
+| `83e2d8168` / `6f46ee419` | Phase 1 | Blockchain core (`uet_chain`) |
+| `ff8cfb76c` / `35579f0b3` | Phase 2 | Web backend APIs + `.gitignore` fixes |
+| `f3e177ee3` / `b338e772c` | Phase 3 | Wallet + Mining Dashboard merged into Account page |
+| `4ac6a9eb8` / `6e2bc2b25` | Phase 4 | Security hardening: Dilithium3 + Ed25519 + KeyManager |
+| `d1ba4221e` / `98ec6f322` | Phase 5 | Knowledge Base & AI: embeddings, MCP HTTP server |
+| `08d352312` / `09cea6bde` | Phase 6 | Multi-Agent RAG chatbot + auth flow audit |
+| `a23781260` / `b7083dc8f` | Cleanup | This session: gitlink fix, Docker fix, daily reporting, push |
 
-**Decision right now:** do not commit yet.
+---
 
-Reason:
+## Part 4: What's Still Incomplete or Missing
 
-- the repo is cleaner than before,
-- the reporting standard is now being established,
-- but the final commit scope still needs one more careful pass before creating the next commit.
+### Critical gaps
+
+1. **`uet_under_development/`** — 4 modules are scaffold-only:
+   - `uet_economic` — economic policy engine
+   - `uet_governance` — voting/proposal system
+   - `uet_market` — market infrastructure
+   - `uet_oracle` — oracle/external data feeds
+   
+2. **Agent system not wired to web** — `uet_agents` Python backend (`api_server.py`) is separate from the Next.js chat API. The web chat uses its own keyword search, not the cognitive memory agent system. These two need to be integrated.
+
+3. **No real LLM integration** — The `UETResponseComposer` and chat API both use keyword matching, not an actual language model. For production-quality chat, an LLM (OpenAI, local model, etc.) needs to be wired in.
+
+4. **Prisma migrations not applied in Docker** — `docker-compose.yml` starts the web server but does not run `prisma migrate deploy` before startup.
+
+5. **No CI/CD pipeline** — `.github/` exists but no workflows were visible for automated testing or deployment.
+
+6. **No automated tests for web/agents** — Only `uet_agents/test_marketing.py` exists. No test coverage for API routes, components, or integration.
+
+### Non-critical but notable
+
+7. **GitHub language stats are misleading** — Shows HTML 45.6%, Rust 37%, TypeScript 1%. This is because `research_uet/` has ~32,500 tracked files (Jupyter notebooks counted as HTML by GitHub's linguist). The actual codebase is primarily Rust + TypeScript + Python. Consider adding a `.gitattributes` file to mark `research_uet/` as documentation so GitHub language stats reflect the real code ratio.
+
+8. **`uet_miner` binary tracked in Git** — `uet_miner.exe` (5MB) and `uet_miner_linux` (4.4MB) are tracked. These should ideally be in `.gitignore` and distributed via GitHub Releases instead.
+
+9. **Documentation folder structure** — `research_uet/Docs`, `uet_web/Docs_software_design`, and `uet_web/docs/software_design` all exist. The authoritative design docs live in `uet_web/docs/software_design/platform_specs` per project standard, but runtime code also checks `Docs_software_design/`. Should be unified long-term.
+
+---
+
+## Part 5: Current Repository State
+
+```
+Branch:  main
+Remote:  origin/main (https://github.com/unityequilibrium/UnityEquilibriumTheory.git)
+Status:  FULLY IN SYNC (no ahead, no behind)
+Latest:  b7083dc8f - Merge branch 'main'
+```
+
+Working tree is clean. No uncommitted changes.
+
+---
+
+## Part 6: Recommended Next Actions (for next session)
+
+1. **Wire `uet_agents` Python backend into the web chat** — Replace or supplement the keyword-based chat API with the cognitive memory agent system
+2. **Add LLM integration** — Connect to OpenAI/Anthropic/local model for real language generation
+3. **Fix `.gitattributes`** — Mark `research_uet/` as documentation to fix GitHub language stats
+4. **Add `uet_miner` binaries to `.gitignore`** — Distribute via GitHub Releases instead
+5. **Begin `uet_under_development` modules** — Start with economic or governance based on priority
+6. **Add Prisma migration step to Docker** — Ensure database schema is applied on container startup
+7. **Set up CI/CD** — At minimum: lint, type-check, and test on push
+
+---
+
+## Handoff Notes
+
+This session was primarily about **infrastructure stabilization**, not feature development. The repository was in a broken state (couldn't commit/push) and is now fully operational. All existing code modules are committed and pushed.
+
+The next session should focus on **feature integration** — specifically connecting the Python agent backend to the web frontend, and beginning work on the undeveloped modules (economic, governance, market, oracle).