Architecture¶

Layer Map¶

flowchart LR
    I["inbound adapters"] --> A["application"]
    W["langgraph orchestration"] --> A
    X["outbound adapters"] --> A
    A --> D["domain"]
    E["example apps"] --> A
    E --> D

Layer Responsibilities¶

`domain`¶

위치: - src/domain_agent/domain/models.py

역할: - agent request lifecycle 모델링 - 상태 전이 규칙 강제 - human review 결과와 실행 규칙 정의

핵심 타입: - Request - RequestStatus - Proposal - ReviewDecision - AgentPlan - PlannedAction - ActionReviewDecision - PlanReviewResult

이 레이어는 LangGraph, LangChain, CLI, DB를 모릅니다.

Domain Modeling Notes¶

domain은 Request aggregate를 중심으로 구성됩니다.

Request: lifecycle과 review state를 소유
Proposal: 사람 검토를 위한 summary
AgentPlan: action 실행 계획
PlanReviewResult: plan 전체와 action별 review 결과

중요한 점:

workflow는 전이 순서를 orchestration
domain은 어떤 전이가 유효한지 정의

즉 "무슨 순서로 실행되는가"와 "무엇이 가능한 상태인가"를 분리합니다.

`application`¶

위치: - src/domain_agent/application/ports.py - src/domain_agent/application/dto.py - src/domain_agent/application/use_cases.py

역할: - 외부 의존성 경계와 use case 정의 - human review payload DTO 정의 - orchestration 실행 use case 제공

핵심 포트: - RequestRepository - ContextProvider - AgentEngine - ActionExecutor

핵심 DTO: - AnalysisResult - AgentWorkResult - ReviewPacket

`orchestration/langgraph`¶

위치: - src/domain_agent/orchestration/langgraph/graph.py - src/domain_agent/orchestration/langgraph/state.py - src/domain_agent/orchestration/langgraph/nodes/deterministic.py - src/domain_agent/orchestration/langgraph/nodes/llm.py

역할: - LangGraph graph 정의 - interrupt/resume 기반 human review orchestration - optional human interaction branch 처리 - deterministic node와 LLM-oriented node 분리

여기서 중요한 변화: - 사람 개입 메커니즘은 별도 gateway가 아니라 LangGraph interrupt()에 위임 - review semantics 자체는 여전히 domain/application이 소유

`adapters/outbound`¶

위치: - src/domain_agent/adapters/outbound/in_memory.py - src/domain_agent/adapters/outbound/langchain.py

역할: - outbound adapter 구현 - deterministic review handler - in-memory repository - in-memory tools - LangChain LCEL 기반 AgentEngine

여기 구현은 "실제 운영용"이 아니라, 코어 구조 검증과 demo 실행을 위한 reference implementation입니다.

`adapters/inbound`¶

위치: - src/domain_agent/adapters/inbound/cli_demo.py - src/domain_agent/adapters/inbound/cli_review.py - src/domain_agent/adapters/inbound/cli_graph.py

역할: - inbound adapter - CLI demo - CLI review collector - graph export command

Why The Current Shape Is Simpler¶

이전 구조에서는 human interaction을 별도 gateway abstraction으로 감쌌습니다.
현재는 이 메커니즘을 LangGraph interrupt로 넘겼습니다.

즉:

review 의미는 템플릿이 유지
review 중단/재개 메커니즘은 LangGraph가 담당

이 분리 덕분에:

추상화 수가 줄어듦
코드 경로가 짧아짐
CLI/API/UI가 같은 resume payload 모델을 공유할 수 있음

Ports And Adapters View¶

현재 구조를 hexagonal / ports-and-adapters 식으로 읽으면 아래처럼 나뉩니다.

domain: business meaning
application/ports.py: abstract ports
application/use_cases.py: use case orchestration
adapters/inbound: CLI 같은 진입점
adapters/outbound: persistence, tools, LangChain adapter
orchestration/langgraph: workflow engine wiring

Generic Core vs Example Apps¶

generic core: - src/domain_agent

example apps: - examples/operational_change - examples/mock_api

원칙: - generic core는 agent application의 공통 의미를 제공 - example app은 구체 도메인 request/adapter만 추가 - example 로직은 패키지 내부를 오염시키지 않음

Keep vs Delegate¶

템플릿이 계속 가져가야 하는 것: - lifecycle 상태 - human review packet shape - review result semantics - partial review / partial execution rules

LangGraph/LangChain에 위임할 것: - interrupt / resume - checkpoint continuation - graph node orchestration - tool-aware planning engine 구현

Code References¶

src/domain_agent/domain/models.py
src/domain_agent/application/ports.py
src/domain_agent/application/dto.py
src/domain_agent/application/use_cases.py
src/domain_agent/orchestration/langgraph/graph.py
src/domain_agent/orchestration/langgraph/state.py
src/domain_agent/orchestration/langgraph/nodes/deterministic.py
src/domain_agent/orchestration/langgraph/nodes/llm.py
src/domain_agent/adapters/outbound/in_memory.py
src/domain_agent/adapters/inbound/cli_demo.py
src/domain_agent/adapters/inbound/cli_review.py
src/domain_agent/adapters/inbound/cli_graph.py