아리(Ari) — AI Life OS

일·삶을 한곳에서 관리하는 한국어 AI 개인비서 아리의 MVP. 핵심 철학: "적을 때는 분류하지 않는다 — 분류·배치·자동화는 아리가." 사용자는 읽고 탭 한 번, 나머지는 아리가 합니다.

MVP 3페이지 — 작업(/tasks) · 인박스(/inbox) · 대시보드(/dashboard). 나머지 10개 내비 항목은 "준비 중" 플레이스홀더(내비 일관성 유지).

workspace/
├─ frontend/   Next.js 16 (App Router, TypeScript) · next-themes · SWR · Vitest · Playwright
├─ backend/    FastAPI · SQLite(SQLModel·Alembic) · Ollama 추상화(모델 비종속, heuristic 폴백)
├─ dev/        개발 문서 (overview.md + phase-0~6)
└─ design-reference/  원본 프로토타입 (픽셀 충실 재현 기준)

개발 포트: 흔한 dev 포트(3000/5173/8000/8080)와 충돌을 피하려고 프론트 :31300 · 백엔드 :31800 을 씁니다. 작업 러너는 make 대신 just 입니다(justfile).

스택

레이어	선택
프론트엔드	Next.js(App Router) + React 19 + TypeScript, 순수 CSS 변수 토큰, next-themes 테마
백엔드	Python + FastAPI + SQLite(SQLModel + Alembic)
LLM	로컬 Ollama + LLMProvider 추상화(모델 비종속, OLLAMA_MODEL 주입). 미가용 시 HeuristicProvider 폴백
테스트	pytest(백엔드) / Vitest·Playwright·axe(프론트)

빠른 시작

0) 사전 설치

Node ≥ 20 · pnpm · Python ≥ 3.11 · uv · just · (선택) Ollama

1) 의존성 + 환경변수 + 시드

just install                                  # frontend(pnpm) + backend(uv) 의존성

cp backend/.env.example backend/.env          # 필요 시 OLLAMA_MODEL 등 수정
cp frontend/.env.local.example frontend/.env.local

just migrate && just seed                     # alembic upgrade head + 시드 적재

2) (선택) Ollama — 모델 비종속

ollama serve &
ollama pull <설치할_모델>      # backend/.env 의 OLLAMA_MODEL 과 일치시킬 것 (특정 모델 강제 아님)

Ollama가 없거나 느리면 자동으로 규칙 기반(HeuristicProvider)으로 분류가 계속됩니다. LLM_PROVIDER=heuristic 로 강제할 수도 있습니다(테스트·오프라인).

3) 실행

just run dev        # backend :31800 + frontend :31300 (개별: just run be / just run fe)
# http://localhost:31300 → / 는 /dashboard 로 리다이렉트

4) 스모크 / 테스트

just health         # /api/health, /api/llm/health
just test           # pytest + vitest
just lint           # ruff + eslint

# E2E (백엔드는 리셋 허용 + heuristic 으로 기동해야 federation/a11y/responsive 전부 통과)
ARI_ALLOW_TEST_RESET=1 LLM_PROVIDER=heuristic uv run --directory backend uvicorn app.main:app --port 31800 &
just e2e            # = pnpm exec playwright test --workers=1

시드 초기화(데모 리셋)

cd backend && rm -f ari.db && uv run alembic upgrade head && uv run python -m app.seed
# 또는 E2E용(가드): ARI_ALLOW_TEST_RESET=1 로 기동 후
curl -X POST http://localhost:31800/api/_test/reset

환경변수

변수	위치	기본값	설명
OLLAMA_HOST	backend .env	http://localhost:11434	Ollama HTTP 엔드포인트
OLLAMA_MODEL	backend .env	(설치 모델 주입)	분류용 모델명 — 비종속(env로만 지정)
LLM_PROVIDER	backend env	auto	auto|ollama|heuristic (테스트/E2E는 heuristic)
LLM_TIMEOUT	backend env	30	분류 1건 타임아웃(초). 초과 시 heuristic 폴백
DATABASE_URL	backend .env	sqlite:///./ari.db	DB 경로
FRONTEND_ORIGIN	backend .env	http://localhost:31300	CORS 허용 출처(콤마구분)
ARI_ALLOW_TEST_RESET	backend env	(미설정)	1이면 /api/_test/reset 허용(E2E 전용, 운영 403)
NEXT_PUBLIC_API_BASE	frontend .env.local	http://localhost:31800	프론트가 호출할 백엔드 베이스

연합(federation) 흐름 — MVP의 핵심

1. 인박스에 한 줄 적기 → 아리가 즉시 작업/일정/아이디어 + 업무/개인 + 행선지 프로젝트로 분류.
2. 확인(탭 한 번) → 실제 task로 실체화(materialized_task_id 연결).
3. 작업 페이지의 개인 › 여행 — 한국에 등장 — 개인 일도 숨기지 않고 업무 작업과 같은 트리에서 필터로만 구분.
4. 작업 데이터로 리스크 레이더(지연·쏠림·의존성)가 자동 재계산, 대시보드가 작업/인박스/결재함을 집계.

데모 스크립트(약 3분)

1. 대시보드 진입 — 아침 브리핑/일정/할 일/목표/결재함·인박스 요약.
2. 인박스에서 다음 주에 한국 놀러가는 비행기 티켓 사기 캡처 → 자동 분류(작업/개인 › 여행 — 한국 + 이유).
3. "좋아요, 그렇게 해줘" → 실체화.
4. 작업 → 개인 필터 → 여행 — 한국에 등장(개인도 숨기지 않음).
5. 업무 필터 → 리스크 레이더 "분기 리포트가 오늘 마감인데 진행 중".
6. 대시보드 복귀 → 요약 반영.

문서

개발 문서 진입점은 dev/overview.md. 빌드 순서: phase-0 → phase-1 → phase-2 → (phase-3 작업 → phase-4 인박스 → phase-5 대시보드) → phase-6 통합.