chore: add c4 spec

2026-06-06 19:22:58 +08:00
commit ca9f1242f8
11 changed files with 2490 additions and 0 deletions
@@ -0,0 +1,103 @@
+views {
+  view index {
+    title 'System Context'
+    description '''
+      Curriculum Project Hub treats a Feishu group as the long-lived project collaboration space.
+      Claude joins only when teachers @Claude, and the Hub creates one AgentRun for that work.
+    '''
+
+    include teacher, admin, hub, feishu, claude, workspace
+  }
+
+  view containers of hub {
+    title 'Target Containers'
+    description 'Main runtime containers and external integrations for the target architecture.'
+
+    include *
+    include teacher, admin, feishu, claude, workspace
+  }
+
+  view permissions of hub {
+    title 'Permission Model'
+    description '''
+      Permissions follow the Feishu Docs pattern: collaborator grants are separate from operation settings.
+      Grants are resource + principal + role; settings decide who may share, comment, copy/download, manage collaborators and invoke Claude.
+    '''
+
+    include permission, project, im, run, db
+    include db.projectEntity, db.groupEntity, db.permissionEntity, db.settingsEntity, db.auditEntity
+    include teacher, admin, feishu
+  }
+
+  view domain_model of hub.db {
+    title 'Core Domain Model'
+    description '''
+      The main correction from the old demo model: project groups and Claude sessions are long-lived,
+      but project locks are owned by AgentRun, not by teacher, chat or session.
+    '''
+
+    include *
+  }
+
+  dynamic view run_lifecycle {
+    title '@Claude Run Lifecycle'
+    description 'A teacher @Claude message creates one AgentRun, which owns the project lock until completion, cancellation or timeout.'
+
+    teacher -> feishu 'send @Claude in project group'
+    feishu -> hub.im 'message event'
+    hub.im -> hub.project 'resolve chat binding'
+    hub.im -> hub.permission 'check trigger permission'
+    hub.im -> hub.run 'create AgentRun'
+    hub.run -> hub.locks 'acquire project lock with run_id'
+    hub.run -> hub.context 'build seed context'
+    hub.run -> hub.runtime 'execute Claude turn'
+    hub.runtime -> claude 'resume/call Claude'
+    hub.runtime -> workspace 'read/write project files'
+    hub.runtime -> hub.mcp 'request extra context if needed'
+    hub.mcp -> hub.context 'resolve run-scoped tools'
+    hub.context -> feishu 'read history by message/thread/chat'
+    hub.runtime -> hub.run 'return result'
+    hub.run -> hub.im 'publish status/result card'
+    hub.im -> feishu 'send/update card'
+    hub.run -> hub.locks 'release run-owned lock'
+
+    include teacher, feishu, claude, workspace
+  }
+
+  dynamic view cancel_lifecycle {
+    title 'Cancel Current Processing'
+    description 'A permitted teacher can cancel the current active run from card action or @Claude cancel command.'
+
+    teacher -> feishu 'click cancel or @Claude cancel'
+    feishu -> hub.im 'callback/event'
+    hub.im -> hub.project 'resolve project group binding'
+    hub.im -> hub.permission 'check cancel permission'
+    hub.im -> hub.run 'cancel active run'
+    hub.run -> hub.runtime 'abort controller if local process is alive'
+    hub.run -> hub.locks 'release lock by run_id'
+    hub.run -> hub.db 'mark AgentRun canceled and audit actor'
+    hub.run -> hub.im 'update status card'
+    hub.im -> feishu 'processing canceled'
+
+    include teacher, feishu
+  }
+
+  dynamic view context_access {
+    title 'On-demand Context Access'
+    description '''
+      The Hub stores anchors and memory, not full Feishu history. Claude can call MCP tools
+      to fetch the current trigger message, reply chain, thread history and recent group messages.
+    '''
+
+    hub.runtime -> hub.mcp 'call get_current_message / get_thread_context'
+    hub.mcp -> hub.context 'authorize by run_id and project_id'
+    hub.context -> hub.db 'read anchors, memory and decisions'
+    hub.context -> feishu 'fetch message/thread/chat history'
+    feishu -> hub.context 'history page'
+    hub.context -> hub.mcp 'filtered context'
+    hub.mcp -> hub.runtime 'tool result'
+    hub.runtime -> claude 'continue with retrieved context'
+
+    include feishu, claude
+  }
+}