# core

## 목적 / 책임

NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduling, persistence, HTTP API, 외부 서비스 adapter를 통해 AI 작업 실행 상태와 자동화 흐름을 관리한다.

## 포함 경로

- `services/core/cmd/` — 서버 실행 entrypoint.
- `services/core/internal/agent/` — agent 모델과 실행 단위.
- `services/core/internal/config/` — 환경 변수 기반 core 설정 로딩.
- `services/core/internal/model/` — 모델 호출 추상 인터페이스와 입출력 타입.
- `services/core/internal/workflow/` — workflow 모델과 서비스.
- `services/core/internal/scheduler/` — River 기반 작업 스케줄링과 job 정의.
- `services/core/internal/notification/` — task notification 모델과 발행 서비스.
- `services/core/internal/http/` — HTTP router, handlers, middleware.
- `services/core/internal/db/` — SQLC 생성 코드, DB pool, persistence 모델.
- `services/core/internal/storage/` — 저장소 abstraction.
- `services/core/internal/adapters/` — OpenAI, A2A, Mattermost, Plane 등 외부 통합.
- `services/core/migrations/`, `services/core/queries/`, `services/core/sqlc.yaml` — DB schema/query 계약.
- `services/core/go.mod`, `services/core/go.sum` — core Go module dependency boundary.
- `services/core/README.md`, `services/core/goose.env.example` — core 실행/운영 문서와 설정 예시.
- `services/core/bin/`, `services/core/Makefile`, `services/core/Dockerfile`, `services/core/docker-compose.yml` — backend-local 개발/배포 도구.

## 제외 경로

- `apps/web/` — backend API를 사용하는 웹 UI이며 core 구현을 직접 소유하지 않는다.
- `apps/mobile/` — 모바일/데스크톱 클라이언트이며 core 내부 패키지를 직접 참조하지 않는다.
- `packages/contracts/` — 공유 API/schema 계약의 소유 영역이다.

## 주요 구성 요소

- `internal/http/router.go` — HTTP route 조립.
- `internal/http/handlers.go` — API handler.
- `internal/config/config.go` — 환경 변수 기반 설정 로딩.
- `internal/model/model.go` — 모델 client interface와 generation DTO.
- `internal/scheduler/river.go` — River scheduler 연결.
- `internal/scheduler/jobs.go` — background job 정의.
- `internal/notification/service.go` — task 완료 notification 발행.
- `internal/adapters/openai/client.go` — OpenAI integration.
- `internal/adapters/a2a/client.go` — A2A integration.
- `internal/db/tasks.sql.go` — SQLC generated query boundary.

## 유지할 패턴

- Go package 경계는 `internal/<domain>` 단위로 유지한다.
- DB 변경은 migration, query, generated code, test를 함께 갱신한다.
- 외부 서비스 호출은 `internal/adapters/<provider>` 아래에 격리한다.
- 환경 변수 기본값과 alias는 `internal/config`에서 관리하고 README의 실행 예시와 어긋나지 않게 유지한다.
- scheduler 변경은 가능한 한 job 단위 테스트를 추가한다.
- HTTP API 변경은 web/mobile 영향과 contracts 반영 필요성을 함께 판단한다.

## 다른 도메인과의 경계

- **contracts**: API shape가 클라이언트와 공유되면 contracts에 먼저 표현하거나 문서화한다.
- **web**: web은 HTTP/API client를 통해 core와 통신한다. core 내부 Go package를 전제하지 않는다.
- **mobile**: mobile은 public API와 notification/auth 계약만 의존한다.
- **workspace-ops**: root helper 변경은 workspace-ops 소유이고, core-local bin 변경만 core 소유다.

## 금지 사항

- `apps/**`의 UI 상태나 라우팅을 core 변경에 끼워 넣지 않는다.
- 외부 provider별 세부 구현을 workflow/service 레이어에 직접 흘리지 않는다.
- SQLC 생성 파일만 수동 수정하지 않는다.
- 테스트 없이 scheduler, persistence, adapter behavior를 크게 바꾸지 않는다.