What
Augment the existing docs/PROJECT_STRUCTURE.md so it explicitly documents the boundary between libs/network-*/ modular protocol libraries and the src/ source tree, and resolves the current ambiguity between src/protocol/ and src/protocols/.
Part of #1083.
Current state
docs/PROJECT_STRUCTURE.md already exists (English + Korean variants) and is referenced from README.md line 698.README.md lines 322-329 describe the eight libs/network-*/ modules well.src/ contains both protocol/ (4 .cpp files: tcp, udp, quic, websocket) and protocols/ (3 directories: grpc, http2, quic) — no document explains why both exist or which is canonical.
Why
A new contributor today cannot tell whether a new feature belongs under libs/network-tcp/ or src/protocol/tcp.cpp or src/protocols/quic/. The cost is a steady stream of misplaced PRs and review time spent relocating files. Documenting the boundary once retires that recurring waste.
Where
docs/PROJECT_STRUCTURE.md (augment)docs/PROJECT_STRUCTURE.kr.md (mirror Korean translation)README.md (verify the existing link still resolves; no new link required)
How
Technical approach
- Decide and codify the rule:
libs/network-*/ — public modular protocol libraries with their own CMakeLists.txt and stable ABI; consumers depend on these.src/ — internal implementation behind network_system::network_system umbrella target; not consumed directly.
- Resolve
src/protocol/ vs src/protocols/:
- Inspect each subtree, identify which is current vs legacy.
- Document the answer in
PROJECT_STRUCTURE.md, file a follow-up cleanup issue if removal is warranted (do NOT remove in this issue).
- Add a "Decision tree: where does new code go?" section with worked examples (new protocol vs new internal helper vs new public header).
- Translate the new sections into
PROJECT_STRUCTURE.kr.md.
Acceptance criteria
What
Augment the existing
docs/PROJECT_STRUCTURE.mdso it explicitly documents the boundary betweenlibs/network-*/modular protocol libraries and thesrc/source tree, and resolves the current ambiguity betweensrc/protocol/andsrc/protocols/.Part of #1083.
Current state
docs/PROJECT_STRUCTURE.mdalready exists (English + Korean variants) and is referenced fromREADME.mdline 698.README.mdlines 322-329 describe the eightlibs/network-*/modules well.src/contains bothprotocol/(4 .cpp files: tcp, udp, quic, websocket) andprotocols/(3 directories: grpc, http2, quic) — no document explains why both exist or which is canonical.Why
A new contributor today cannot tell whether a new feature belongs under
libs/network-tcp/orsrc/protocol/tcp.cpporsrc/protocols/quic/. The cost is a steady stream of misplaced PRs and review time spent relocating files. Documenting the boundary once retires that recurring waste.Where
docs/PROJECT_STRUCTURE.md(augment)docs/PROJECT_STRUCTURE.kr.md(mirror Korean translation)README.md(verify the existing link still resolves; no new link required)How
Technical approach
libs/network-*/— public modular protocol libraries with their own CMakeLists.txt and stable ABI; consumers depend on these.src/— internal implementation behindnetwork_system::network_systemumbrella target; not consumed directly.src/protocol/vssrc/protocols/:PROJECT_STRUCTURE.md, file a follow-up cleanup issue if removal is warranted (do NOT remove in this issue).PROJECT_STRUCTURE.kr.md.Acceptance criteria
PROJECT_STRUCTURE.mdhas a "libs/ vs src/" section with an explicit ruleprotocol/vsprotocols/ambiguity addressed (status documented; cleanup if needed deferred to a follow-up issue)