Ariadne

Ariadne는 여러 조직에서 발생하는 오류를 통합하고, 연결된 저장소와 읽기 전용 실행 환경을 분석해 수정·검증·병합 요청까지 이어 주는 플랫폼이다.

오류 분석과 수정 작업에는 IOP의 LLM 호출 및 CLI 실행 기능을 사용한다. 오류 이력, 조직과 권한, 연결 대상, 작업 흐름, 승인, 보고, 감사 기록의 기준 시스템은 Ariadne다.

현재 상태

Ariadne는 현재 기반 스캐폴드를 안정화하는 단계다.

제품 방향과 구현 순서는 로드맵과 전역 Milestone 실행 순서에서 확인한다.

개발용 PostgreSQL, 마이그레이션, 서버를 함께 실행한다.

docker compose up --build

실행 후 상태를 확인한다.

curl http://localhost:18080/healthz
curl http://localhost:18080/readyz

로컬 Go 도구로 서버를 직접 실행하려면 먼저 PostgreSQL만 시작하고 .env.example의 환경 변수를 내보낸다.

docker compose up -d database
set -a
. ./.env.example
set +a
make migrate
make run

직접 실행한 서버의 기본 주소는 http://localhost:8080이다. 데이터베이스 설정 없이도 서버는 시작할 수 있지만 /readyz는 준비되지 않은 상태를 반환한다.

make client-get
cd apps/client
flutter run -d chrome

목적	명령	비고
전체 개발 환경 실행	`docker compose up --build`	PostgreSQL, migration, Go 서버
Go 서버 실행	`make run`	`.env.example` 기준 환경 변수 필요
DB migration 적용	`make migrate`	migration 전용 DB 역할 사용
Go build	`make build`	`go build ./...`
Go test	`make test`	`go test ./...`
Go 정적 검사	`make vet`	`go vet ./...`
Go format	`make fmt`	`apps/`, `internal/`의 Go 파일 수정
Flutter 의존성 설치	`make client-get`	lockfile 강제 사용
Flutter test	`make client-test`	의존성 설치 포함
Flutter 정적 분석	`make client-analyze`	의존성 설치 포함
Flutter web release build	`make client-build`	의존성 설치 포함
전체 기본 검사	`make check`	Go build/test/vet와 Flutter test/analyze/build

경로	역할
`apps/server/cmd/ariadne/`	Go 서버 진입점
`apps/migrate/cmd/ariadne-migrate/`	전용 DB migration 명령
`apps/client/`	Flutter 웹 사용자 화면
`internal/domain/`	조직, 오류, 실패, 수정 작업의 핵심 모델과 규칙
`internal/integration/`	IOP 등 외부 실행 계층과의 adapter 경계
`internal/platform/`	설정, 로깅, DB, HTTP 서버, bootstrap
`contracts/`	외부 오류 입력과 IOP 실행·실패 JSON 계약
`deploy/`	개발·배포 기반 구성
`docs/`	사람을 위한 최신 구조·개발 가이드
`agent-ops/`	AI 작업 규칙과 프로젝트 workflow
`agent-roadmap/`	제품 방향, Phase, Milestone

Ariadne는 다음 두 가지 수정 흐름을 지원하는 방향으로 개발한다.

자동 수정이 불가능하거나 검증에 실패하면 저장소를 변경하지 않고 분석 결과만 보고한다. 병합은 항상 사용자가 승인한다.

오류 입력 자격 증명은 조직과 프로젝트에 귀속된다. 입력 본문이 조직이나 프로젝트를 임의로 선택하지 않으며, 등록된 출처 규칙이 오류의 저장소와 읽기 전용 실행 환경을 결정한다.

IOP의 언어와 운영 관례는 공유하지만 IOP의 제어부·edge·실행 node 계층을 복제하지 않는다. Ariadne는 독립적으로 build·배포할 수 있어야 한다.

작업 전 루트 AGENTS.md와 프로젝트 규칙을 먼저 확인한다.
변경 경로에 대응하는 domain rule을 코드 변경 전에 읽는다.
- internal/domain/**: domain-model
- internal/integration/**, contracts/**: integrations
- internal/platform/**, apps/server/**, apps/migrate/**, deploy/**: platform
- apps/client/**, .fvmrc: client
로컬 활성 후보는 agent-roadmap/current.md, 공유 제품 방향은 로드맵에서 확인한다.
조직 소유 데이터는 반드시 조직 범위 transaction과 강제 RLS 경계 안에서 접근한다.
migration, 서버 runtime, identity 조회 DB 역할을 분리하고 runtime pool을 조직 범위 밖으로 노출하지 않는다.
운영 환경 연결은 읽기 전용이다. 별도 권한·승인 설계 없이 쓰기 기능이나 IOP의 직접 merge 권한을 추가하지 않는다.
로컬 형제 저장소를 정식 build dependency로 사용하지 않는다.

로드맵과 변경 경로의 domain rule에서 범위와 제약을 확인한다.
기존 package와 directory 경계를 유지하며 구현한다.
DB 변경은 internal/platform/database/migrations/에 순서가 보장되는 새 migration으로 추가한다. 적용된 migration의 checksum은 바꾸지 않는다.
변경 범위별 test와 정적 검사를 실행한다.
전체 검증이 필요하면 make check를 실행한다.

PostgreSQL 권한·RLS 통합 검사는 Docker 사용 가능 여부와 전용 역할 환경 변수를 확인한 뒤 별도로 수행한다. 자세한 절차는 개발 가이드를 따른다.

.env.example은 로컬 실행용 개발 값을 제공한다. 실제 비밀값이 있는 .env는 저장소에 commit하지 않는다.

이름	설명	필수
`ARIADNE_ENVIRONMENT`	실행 환경 이름, 기본값 `development`	아니오
`ARIADNE_HTTP_ADDRESS`	HTTP 수신 주소, 기본값 `:8080`	아니오
`ARIADNE_DATABASE_URL`	runtime 역할의 PostgreSQL 접속 주소	DB 준비 상태에 필요
`ARIADNE_DATABASE_IDENTITY_URL`	identity 조회 역할의 PostgreSQL 접속 주소	DB 준비 상태에 필요
`ARIADNE_DATABASE_MIGRATION_URL`	migration 전용 PostgreSQL 접속 주소	migration 시 필요
`ARIADNE_DATABASE_RUNTIME_ROLE`	기대하는 runtime DB 역할 이름	DB 사용 시 필요
`ARIADNE_DATABASE_IDENTITY_ROLE`	기대하는 identity DB 역할 이름	DB 사용 시 필요
`ARIADNE_MIGRATION_LOCK_TIMEOUT`	동시 migration lock 대기 한도, 기본값 `30s`	아니오
`ARIADNE_IOP_ENDPOINT`	IOP 연결 주소	현재 아니오
`ARIADNE_SHUTDOWN_TIMEOUT`	정상 종료 대기 시간, 기본값 `10s`	아니오