mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-07-28 17:06:05 +00:00
57ba19b877
HEXAGONAL_ARCHITECTURE_zh.md now carries rules only: the two orthogonal boundaries, the AWS three-folder mapping, the two kinds of secondary adapter, and how the boundaries are mechanically enforced. The feedback walkthrough, its known gaps, and its todo list move to a module document, so the guide stays readable as more modules are migrated. Two corrections to the guide, both of which would have misled a reader: - Ports belong inside `domain/`, not beside it. AWS places `ports/` as a subdirectory of `domain/` and describes the domain folder as "domain and interfaces"; lifting ports into a third top-level layer would make the domain depend on an outside package to declare its own needs. The guide now states this explicitly, since the opposite reading is common. - The walkthrough had the service calling RunLookup before building the aggregate. The code does the reverse, and the order matters: validation runs before any port call, so an invalid rating on a nonexistent run is reported as InvalidRatingError rather than RunNotFoundError. The same section also called that check authorization; it is referential integrity, and authorization is the router's owner_check plus this check taken together -- which is why the port takes no user_id. FEEDBACK_DESIGN_zh.md is new and follows the SCHEDULE_DESIGN_zh.md shape: the aggregate and its invariants, both ports and the conventions that matter more than their signatures, the four use cases, both adapters, the walkthrough, the test layering, an extension guide, and a pitfall list. Three things it records that were not written down anywhere: - The aggregate reads the system clock in its default factory, which schedule deliberately avoids. Acceptable while the timestamp is only a bookkeeping stamp and feeds no rule; noted with the condition that would force a change. - A repository that explicitly inherits its Protocol turns a misspelled method into a silent None, because the inherited body is `...`. Hit for real during the move. isinstance() cannot detect it, so asserting "the port is satisfied" is not a substitute for asserting return values. - RunLookup has no contract test against a real RunStore. A renamed key in the dict RunStore.get() returns would turn every rating into a 404 with the suite still green. README.md indexes both under Quick Links, next to ARCHITECTURE.md.
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# Documentation
|
||
|
||
This directory contains detailed documentation for the DeerFlow backend.
|
||
|
||
## Quick Links
|
||
|
||
| Document | Description |
|
||
|----------|-------------|
|
||
| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture overview |
|
||
| [HEXAGONAL_ARCHITECTURE_zh.md](HEXAGONAL_ARCHITECTURE_zh.md) | 六边形（Ports & Adapters）分层总纲：规则、AWS 官方结构对应、两类从适配器、边界如何被测试守住 |
|
||
| [FEEDBACK_DESIGN_zh.md](FEEDBACK_DESIGN_zh.md) | 用户反馈模块设计：首个完成的六边形切片，聚合/端口/适配器逐层走读与二次开发指引 |
|
||
| [API.md](API.md) | Complete API reference |
|
||
| [AUTH_DESIGN.md](AUTH_DESIGN.md) | User authentication, CSRF, platform-trust (IM / Internal Auth), and per-user isolation |
|
||
| [SSO.md](SSO.md) | OIDC / SSO single sign-on |
|
||
| [IM_CHANNEL_CONNECTIONS.md](IM_CHANNEL_CONNECTIONS.md) | IM channel user binding (`channel_connections`) |
|
||
| [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |
|
||
| [SETUP.md](SETUP.md) | Quick setup guide |
|
||
|
||
## Feature Documentation
|
||
|
||
| Document | Description |
|
||
|----------|-------------|
|
||
| [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
|
||
| [RUN_EVENT_STREAM.md](RUN_EVENT_STREAM.md) | Persisted run event stream contract: envelope, producers, consumers, and known gaps |
|
||
| [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
|
||
| [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
|
||
| [SANDBOX_MEMORY_PROFILING.md](SANDBOX_MEMORY_PROFILING.md) | Sandbox memory baseline and runtime comparison guide |
|
||
| [summarization.md](summarization.md) | Context summarization feature |
|
||
| [plan_mode_usage.md](plan_mode_usage.md) | Plan mode with TodoList |
|
||
| [AUTO_TITLE_GENERATION.md](AUTO_TITLE_GENERATION.md) | Automatic title generation |
|
||
|
||
## Development
|
||
|
||
| Document | Description |
|
||
|----------|-------------|
|
||
| [TODO.md](TODO.md) | Planned features and known issues |
|
||
|
||
## Getting Started
|
||
|
||
1. **New to DeerFlow?** Start with [SETUP.md](SETUP.md) for quick installation
|
||
2. **Configuring the system?** See [CONFIGURATION.md](CONFIGURATION.md)
|
||
3. **Understanding the architecture?** Read [ARCHITECTURE.md](ARCHITECTURE.md)
|
||
4. **Building integrations?** Check [API.md](API.md) for API reference
|
||
5. **Wondering why the layers are split the way they are?** Read [HEXAGONAL_ARCHITECTURE_zh.md](HEXAGONAL_ARCHITECTURE_zh.md) for the rules, then [FEEDBACK_DESIGN_zh.md](FEEDBACK_DESIGN_zh.md) for a worked example
|
||
|
||
## Document Organization
|
||
|
||
```
|
||
docs/
|
||
├── README.md # This file
|
||
├── ARCHITECTURE.md # System architecture
|
||
├── HEXAGONAL_ARCHITECTURE_zh.md # Hexagonal layering rules (zh)
|
||
├── FEEDBACK_DESIGN_zh.md # Feedback module design (zh) — first hexagonal slice
|
||
├── API.md # API reference
|
||
├── AUTH_DESIGN.md # User authentication and isolation design
|
||
├── CONFIGURATION.md # Configuration guide
|
||
├── SETUP.md # Setup instructions
|
||
├── FILE_UPLOAD.md # File upload feature
|
||
├── PATH_EXAMPLES.md # Path usage examples
|
||
├── summarization.md # Summarization feature
|
||
├── plan_mode_usage.md # Plan mode feature
|
||
├── STREAMING.md # Token-level streaming design
|
||
├── RUN_EVENT_STREAM.md # Persisted run event stream contract
|
||
├── AUTO_TITLE_GENERATION.md # Title generation
|
||
├── TITLE_GENERATION_IMPLEMENTATION.md # Title implementation details
|
||
└── TODO.md # Roadmap and issues
|
||
```
|