---
title: Metrix System Architecture Overview
type: curated
permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-system-architecture-overview
stable_id: 44fc1143-7dee-4e0a-8086-42b65f39e0de
scope: project
project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: architecture
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
source_git_commits:
- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 29
source_revisions: {}
source_dispositions:
  processed: 29
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids:
- git:server/app/main.py
- git:server/app/modules/registry.py
- git:server/app/core/permissions.py
- git:server/app/core/security.py
- git:server/app/db/init.py
- git:server/app/migrations/registry.py
job_cited_source_ids: []
conflicts: []
supersedes: []
preferences: []
source_cursor: 162
source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-19T02:32:26.402300+00:00'
updated_at: '2026-09-23T15:09:27.554762+00:00'
tags:
- architecture
- fastapi
- vue
- modules
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

## Architecture Overview (2026‑08‑26)

| Layer | Component | Key Notes |
|------|-----------|-----------|
| **API Gateway / FastAPI Core** | `git:server/app/main.py` | FastAPI app factory, OpenAPI, CORS, SPA fallback |
| **Module Registry** | `git:server/app/modules/registry.py` | Discovers `APP_MODULE` objects, validates keys & deps |
| **Permission Framework** | `git:server/app/core/permissions.py` | Action‑based RBAC; `action:* → read` |
| **Security Utils** | `git:server/app/core/security.py` | PBKDF2‑SHA256 hashing, `mtx_` API‑tokens, Fernet secrets |
| **Database Sub‑system** | ORM models, `git:server/app/db/init.py`, migrations | SQLAlchemy sessions, alembic‑style registry |
| **Containers Module** | Docker client, WS xterm.js terminal | `modules/containers/...` |
| **Database Module** | Export/Import, APScheduler jobs, pagination |
| **Scripts Execution Platform** | Preset Docker images, quota, retention policies |
| **Storage API** | FTP/SFTP adapters, file‑tree service (depth/size caps) |
| **Offline Docker Deployment** | `scripts/build_docker.py` → `metrix‑app‑latest.tar` (+ optional MySQL & internal PyPI) |
| **Front‑End SPA** | Vue 3 + TypeScript + Vite + Naïve‑UI; i18n (EN/ZH), dark/light themes, Monaco + Shiki, Playwright tests |
| **CI / Regression** | Playwright end‑to‑end suite (`tests/regression/framework.spec.ts`) |

**Module Interaction Flow** – router guard → auth store → API client → registered pages → background job polling.

The architecture reflects the stable state captured on **2026‑08‑26** (see Current State).