docs: document backend code structure

[illegalcall]

Summary

• add a backend code structure guide for package ownership
• document the rules for domain vs feature packages vs capability adapters vs HTTP
• link the guide from the docs index

Notes

• docs only; no package moves in this PR
• intended to guide follow-up reviews like PR feat(api): projects route shell (7 routes, REST-corrected) — #20 #24

Testing

• git diff --check

[neversettle17-101]

LGTM

[greptile-apps]

Greptile Summary

Adds a new docs/backend-code-structure.md guide that codifies package ownership rules for the Go backend, and links it from docs/README.md. The document is thorough and consistent with the actual codebase layout across the named packages.

• The package-role descriptions, import-graph rules, interface-placement guidance, and "Adding New Code" checklists all match the observed structure and align well with architecture.md.
• The "Current Tree" snapshot omits internal/daemonmeta/, internal/processalive/, internal/runfile/, and internal/integration/ — all of which exist on disk — leaving their ownership undocumented.

Confidence Score: 4/5

Docs-only change; no production code is modified and the guidance is broadly accurate.

The guide is well-written and matches the real codebase for every package it names. The "Current Tree" snapshot is incomplete — four packages that exist on disk are absent — which could mislead contributors about where new utility or infrastructure code belongs.

docs/backend-code-structure.md — the Current Tree section needs the missing packages added before the doc is used as a definitive reference.

Important Files Changed

Filename	Overview
docs/README.md	Adds one table row linking to the new backend-code-structure.md guide; insertion order and description are accurate.
docs/backend-code-structure.md	New 382-line package-ownership guide; content matches the actual codebase well but the "Current Tree" section omits four real packages (daemonmeta, processalive, runfile, integration).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CLI[internal/cli]
    HTTPD[internal/httpd]
    DAEMON[internal/daemon]
    SERVICE[internal/service/*]
    SESSION_MGR[internal/session_manager]
    LIFECYCLE[internal/lifecycle]
    PORTS[internal/ports]
    ADAPTERS[internal/adapters/*]
    DOMAIN[internal/domain]
    STORAGE[internal/storage/sqlite]
    CDC[internal/cdc]
    TERMINAL[internal/terminal]
    CONFIG[internal/config]

    DAEMON --> SERVICE
    DAEMON --> ADAPTERS
    DAEMON --> STORAGE
    DAEMON --> CDC
    DAEMON --> LIFECYCLE
    DAEMON --> HTTPD
    DAEMON --> CLI
    DAEMON --> CONFIG

    HTTPD --> SERVICE
    HTTPD --> TERMINAL
    CLI --> HTTPD

    SERVICE --> DOMAIN
    SERVICE --> STORAGE

    SESSION_MGR --> PORTS
    SESSION_MGR --> LIFECYCLE
    SESSION_MGR --> STORAGE

    LIFECYCLE --> DOMAIN
    LIFECYCLE --> STORAGE

    ADAPTERS --> PORTS
    ADAPTERS --> DOMAIN

    STORAGE --> DOMAIN
    CDC --> STORAGE

    style DOMAIN fill:#d4edda,stroke:#28a745
    style PORTS fill:#cce5ff,stroke:#004085
    style ADAPTERS fill:#fff3cd,stroke:#856404

Loading

_{Reviews (1): Last reviewed commit: "docs: resolve backend structure doc conf..." | Re-trigger Greptile}

[greptile-apps]

Current Tree omits several real packages

The "Current Tree" section is missing at least four packages that exist on disk: internal/daemonmeta/ (build/version metadata), internal/processalive/ (liveness checking for agent processes), internal/runfile/ (daemon run-file / lock management), and internal/integration/ (integration tests). A developer looking for the right home for code related to any of these areas won't find guidance here and may place new code in the wrong package or, worse, create a duplicate.