# Architecture Study — MiroFish SaaS Migration

**Date:** 2026-08-23 (+07:00)
**Repository:** `/Users/kunthawat/Gitea/MiroFish`
**HEAD:** `89d04e7`
**Status:** complete — plan only; no production source changes

## Scope

Reviewed frontend i18n/rendering, backend API/entry points, Zep integration, LLM prompt paths, persistence, auth/security posture, role/tenant requirements and Docker runtime.

## Evidence

- Working tree was clean at start and after baseline verification.
- `npm run build` passed; Vite emitted chunk-size and `pendingUpload.js` import warnings.
- `python3 -m compileall -q backend/app backend/run.py backend/scripts` passed.
- `git diff --check` passed.
- Backend route inventory: 64 routes; no auth middleware found.
- Frontend locale inventory: `en` and `th` have matching 648 flattened keys; `zh` is still present and is the fallback/default path.
- Current built frontend still contains CJK code points in generated HTML/JS.
- Zep usage was traced through graph build, entity reader, search tools, graph memory updater, profile generation and ReportAgent.
- Current project/task/simulation/report state is mostly filesystem/in-memory scoped globally, not by user or organization.
- Independent SaaS audit confirmed additional risks: raw request-body logging, raw exception/path exposure, non-idempotent frontend retries, global history/debug routes, process-local pending uploads and a report-status HTTP method/body mismatch.

## Decisions captured in plan

- Use PostgreSQL as SaaS system of record; add tenant scope from v1.
- Use LLM for structured memory extraction/merge/summary/query reasoning, not for durable storage or unbounded search.
- Preserve internal memory result contracts while replacing Zep implementation.
- Use exactly `super_admin`, `admin`, `user` with backend-enforced policy.
- Default product locale recommendation: Thai, with English switcher.
- Move long-running work to durable workers before calling the system production SaaS-ready.

## Risks/open decisions

- Need user decision on whether user-uploaded Chinese content must also be translated/hidden.
- Need user decision on multi-organization scope, invite flow, Zep data migration and LLM settings scope.
- Python runtime on the current host is 3.14 while project metadata requires Python 3.11–3.12; compile success is not full runtime proof.

## Exact next action

Get M0 answers, then create PR-sized implementation batches starting with persistence/auth contracts and locale/API error contracts. Do not begin by deleting Zep files without first implementing the local memory interface and storage schema.