<a id="stack-overview"></a>
# 기술 스택과 배포 형태

ARTEX는 Go backend와 static-export Next.js UI를 한 binary에 embed할 수 있는 application이다. 필수 PostgreSQL, traffic용 SQLite/filesystem, 외부 LLM·MCP·search·notification service를 연결한다. 이 revision의 direct dependency는 Go 12개, web runtime 41개, web development 15개로 총 68개다. Go manifest explicit require는 53개지만 selected build list는 root 제외 183개이고, 현재 production import closure는 49 module이다. npm lock record는 773개다. Direct 역할은 [직접 의존성](contracts/dependencies.md#dependency-reference), exact selected/import/lock location은 [전이 의존성·lock 색인](contracts/dependency-lock.md#dependency-lock-reference)이 소유한다. [Go manifest](evidence:go-module) [web manifest](evidence:web-package) [web lock](evidence:web-lock)

<a id="backend-stack"></a>
## Backend

| 구성 | 선언·선택 version | 현재 역할 |
|---|---|---|
| Go | module `go 1.26.3`; CI `1.26` | HTTP server, scheduler, agent host, proxy, storage orchestration |
| Norma | `v0.4.3` | provider/session, tool loop, Skill/MCP, transcript/context SDK |
| pgx | `v5.10.0` | PostgreSQL driver/pool |
| modernc SQLite | `v1.52.0` | CGO-free traffic index와 optional FTS5 |
| go-mitmproxy | `v1.9.2` | HTTP(S) recording proxy |
| dnsx + miekg/dns | `v1.2.3` + `v1.1.72` | asset DNS enrichment와 DNS protocol |
| golang-jwt + x/crypto | `v5.3.1` + `v0.55.0` | JWT와 bcrypt authentication |

표는 주요 실행 역할을 요약한 것이다. Go direct dependency 12개는 [Go direct 목록](contracts/dependencies.md#go-direct-dependencies), manifest indirect 41개는 [explicit indirect 목록](contracts/dependency-lock.md#go-indirect-dependencies), module graph 183개와 production import 49개는 각각 [selected build list](contracts/dependency-lock.md#go-selected-build-list)와 [import closure](contracts/dependency-lock.md#go-production-import-closure)를 본다.

<a id="frontend-stack"></a>
## Frontend

`package.json`은 Next `^16.2.9`, React/React DOM `^19.2.7`, TypeScript `^5.9.3` 범위를 선언하고 현재 lockfile은 각각 `16.2.9`, `19.2.7`, `19.2.7`, `5.9.3`을 선택한다. App Router UI가 상대 `/api`를 호출하고 네 SSE 경로는 native `EventSource`를 쓴다. Graph는 G6/Graphin/XYFlow, table은 TanStack Table, chart는 Recharts가 맡는다. [runtime direct 41개](contracts/dependencies.md#web-runtime-dependencies)와 [development direct 15개](contracts/dependencies.md#web-dev-dependencies)에 manifest range와 lock version을 기록하고, [lock 전수 색인](contracts/dependency-lock.md#web-lock-summary)은 root 1 + package location 772개를 exact version으로 고정한다.

Static build는 `NEXT_EXPORT=1 next build`의 `web/out`을 `server/webui/dist`로 복사하고 `embedui` build tag로 binary에 넣는다. `package.json`의 caret range를 exact pin으로 해석하면 안 되며 재현 입력은 lockfile과 `npm ci`다. [web scripts](contracts/dependencies.md#web-script-contract)

<a id="storage-stack"></a>
## Storage

| 저장소 | 소유 데이터 | startup 성격 |
|---|---|---|
| PostgreSQL | task, graph, asset, agent/config, finding, audit, notification | embedded `schema.sql`을 적용; 두 LLM ledger는 별도 best-effort ensure |
| SQLite | traffic metadata, body reference, FTS | `-data` 아래 생성; FTS5 적용 실패 시 검색 일부 비활성 가능 |
| filesystem | traffic body/blob, evidence, transcript/archive, JWT key, skills, update artifact | 일부 교체·이동은 DB transaction 밖 |
| embedded UI | static export | `embedui` tag가 있는 binary에만 포함 |

<a id="external-dependencies"></a>
## 외부 runtime 경계

- PostgreSQL server. Compose는 `postgres:16-alpine`을 쓰고 외부 DB 배포는 별도 version 계약이 없다.
- Anthropic/OpenAI-compatible LLM endpoint와 optional HTTP/HTTPS/SOCKS5 proxy.
- stdio, Streamable HTTP, legacy SSE MCP server와 local Skill/custom tool process.
- DDGS/Brave/Tavily/DeepSeek search, HTTP notification target, GitHub release API/download.
- 대상 시스템으로 향하는 Bash, WebFetch, browser, MCP, custom command/HTTP traffic. 모든 egress가 recording proxy나 하나의 scope gate를 통과하지 않는다.

<a id="packaging-stack"></a>
## Build·package·container

`build.sh`는 frontend install/export, asset sync, `CGO_ENABLED=0` cross-build, optional ZIP/checksum/UPX를 조립한다. Application option 5개와 env 14개는 [build contract](contracts/dependencies.md#build-contract)에 있다. Default release matrix는 Linux amd64/arm64, Darwin amd64/arm64, Windows amd64 5개다. [build script](evidence:build-script)

Compose는 published `autumn27/artex:${ARTEX_TAG:-latest}`와 PostgreSQL을 시작한다. 8787은 host 모든 interface에 publish하고 8788은 host loopback에만 publish하며 `.env` input은 [10개](contracts/dependencies.md#compose-inputs)다. Runtime image는 Python 3.12 slim/bookworm와 Node 20을 설치하지만 release frontend job은 Node 22를 쓴다. Image가 설치하는 세 Playwright package는 `@latest`라 source revision만으로 exact image content를 고정하지 못한다. [Compose](evidence:compose) [Dockerfile](evidence:dockerfile) [release workflow](evidence:release-workflow)

Compose 주석은 `/app/data`가 `jwt.key`도 담는다고 적지만 application의 실제 기본 위치는 `<BaseDir>/jwt.key`, 즉 image에서 `/app/jwt.key`다. 현재 `./data:/app/data` mount는 그 파일을 보존하지 않는다. Backup 경계와 명령은 [운영 문서](operations.md#paths)를 본다.