cowork-local/agent/knowledge/project_map.md

Project Map — Cowork Local (dành cho agent sửa bug UI/UX)

Nguồn sự thật: README.md, docs/architecture/ADR-001-layered-architecture.md, docs/governance/contributor-recipes.md. File này chỉ tóm tắt phần một người sửa bug UI cần biết.

---

1. Bốn tầng

presentation/  PySide6 UI — Shell, NavRail, Chat, Scheduling, Settings, Dashboard
      ↓
application/   Orchestration thuần Python — Conversations, Scheduling, Workspaces, Monitoring, Routing
      ↓
domain/        Entity, ExecutionRequest bất biến, AgentEvent, Descriptor (thuần Python)
      ↑
infrastructure/  Adapter — LLM provider, persistence atomic JSON, Keyring SecretStore, MCP

• domain/ và application/ không được import PySide6/PyQt/ui/app (scripts/check_imports.py::FORBIDDEN_MODULE_PREFIXES).
• Widget chỉ gọi xuống service của application/, không chạm SQLite/JSON/LLM trực tiếp.
• Mọi module production <= 400 LOC.

2. ⚠️ Hai thư mục UI cùng tồn tại — điểm dễ sửa nhầm file nhất

Thư mục	Vai trò hiện tại	Sửa bug ở đây khi
presentation/	Kết quả refactor R08 — các màn đã tách module	Bug thuộc Chat, Co4E, Dashboard, Folder, Graph, Scheduling, Settings, Shell
ui/	Vẫn đang chạy, không phải code chết	Bug thuộc Monitoring, Workspace, các dialog, icon, widget dùng chung

presentation/ vẫn import ngược sang ui/ cho phần dùng chung, ví dụ:

presentation/shell/page_registry.py:14   from ...ui.monitoring_tab import MonitoringTab
presentation/shell/main_window.py:38     from ...ui.workspace_tab import WorkspaceTab
presentation/dashboard/dashboard_tab.py:24  from cowork_local.ui.icons import icon

Luật: trước khi sửa, grep tên class/hàm trên cả hai thư mục. Sửa bản không được import vào runtime là lỗi "đã fix nhưng user vẫn thấy lỗi" phổ biến nhất của repo này.

grep -rn "class DashboardTab" ui/ presentation/

3. Điểm vào & trạng thái

File	Vai trò
app.py, __main__.py	Bootstrap QApplication, dựng MainWindow
presentation/shell/main_window.py	Cửa sổ chính, _nav_defs, top bar, toast, help agent
presentation/shell/page_registry.py	Chuyển trang; Dashboard/Schedule/Monitoring dựng lười
presentation/shell/nav_rail.py	Nav rail trái, thu gọn/mở rộng, cây project & recents
presentation/shell/top_bar.py	Thanh trên: theme switch, language switch
presentation/shell/toast.py	Popup "task xong" góc trên trái
state.py	AppContext — cầu nối UI ↔ service
config.py	Đọc/ghi cấu hình người dùng (theme, ngôn ngữ, provider...)
paths.py	Vị trí dữ liệu runtime (%USERPROFILE%\.cowork_local)
theme/	Toàn bộ màu sắc & stylesheet (xem theme_tokens.md)
i18n/	Toàn bộ chuỗi hiển thị (xem i18n_rules.md)

Hệ quả của "dựng lười" khi debug

Dashboard, Schedule và Monitoring chưa tồn tại cho tới lần đầu người dùng bấm vào. Nghĩa là:

• Bug "lần đầu mở màn X bị nhấp nháy / sai theme / sai ngôn ngữ" gần như luôn nằm ở _ensure_page / _goto chứ không nằm trong widget của màn đó.
• Widget dựng lười bỏ lỡ các sự kiện đã phát trước đó (đổi theme, đổi ngôn ngữ). Xem qt_pitfalls.md P07.

4. Bảng đối chiếu tính năng → file

Khu vực	File chính
Chat / composer / bubble	presentation/chat/ (chat_panel.py, composer_widget.py, chat_bubble_style.py)
Co4E canvas & node	presentation/co4e/ (co4e_canvas_widget.py, node_property_panel.py, canvas_geometry.py)
Dashboard & biểu đồ	presentation/dashboard/ + ui/spline_chart.py, ui/widgets.py
Folder / preview tài liệu	presentation/folder/ (folder_tab.py, code_editor.py, office_document_renderer.py)
GraphRAG	presentation/graph/
Lịch / Kanban	presentation/scheduling/
Settings	presentation/settings/ + ui/settings_dialog.py
Monitoring (8 sub-view)	ui/monitoring_tab.py + presentation/monitoring/
Workspace + sub-tab	ui/workspace_tab.py, ui/cowork_tab.py, ui/co4e_tab.py
Dialog (login, permission, skill, task...)	ui/*_dialog.py
Icon	ui/icons.py
Widget dùng chung (StatCard, BudgetCard...)	ui/widgets.py

5. Test

Đường dẫn	Nội dung
tests/ui/	Test widget, có conftest.py riêng
tests/integration/	Test ghép nhiều thành phần
tests/e2e/test_smoke.py	Smoke test bản release
tests/characterization/	Chốt hành vi hiện tại trước khi refactor

Chạy headless: QT_QPA_PLATFORM=offscreen pytest tests/ui -q. 64/108 module test dựng widget thật, nên môi trường phải có PySide6.