ai-contract-platform/docs/adr/0001-v2-technology-stack.md

# ADR 0001: V2 Technology Stack

Date: 2026-06-22

## Status

Accepted

## Context

V2 is a full rebuild. The old V1 system and old `shared-*` repositories are preserved as references, but new V2 development should avoid continuing multiple shared mainlines.

The product needs:

- A fast enterprise contract workflow.
- A reusable AI platform boundary.
- Strong database and tenant isolation.
- Contract-first API and SDK development.
- Simple local development and production deployment.
- A stack the team can maintain without carrying Python, Java, and vendored SDK variants at the same time.

## Decision

V2 will use four first-class engineering roots in `D:\yuqei-project\ai-contract-platform` from day one:

- `yuqei-contract-platform`
- `yuqei-ai-platform`
- `yuqei-ai-sdk-python`
- `yuqei-infra`

The repository is one Git development line, but the architecture is not a temporary mixed workspace. Each root is treated as a final project boundary now.

### Frontend

- `yuqei-contract-platform/apps/contract-web`
- Next.js + React + TypeScript
- Ant Design or a small internal design system wrapper during early MVP
- `yuqei-contract-platform/packages/design-system` for tokens, layout primitives, workflow components, and UI conventions

Reason:

- The team already has Next.js experience from V1.
- It supports enterprise dashboards and route-level composition well.
- It keeps frontend/backend contract usage straightforward through generated TypeScript types.

### Backend

- `yuqei-contract-platform/services/contract-api`
- Python 3.12+
- FastAPI
- SQLAlchemy 2.x
- Alembic
- Pydantic v2

Reason:

- The contract system is already Python/FastAPI oriented.
- AI, document parsing, RAG, SDK, and testing ecosystems are stronger and faster to iterate in Python.
- Avoids continuing Java and Python dual mainlines.

### AI Platform

- `yuqei-ai-platform/services/ai-platform-api`
- Python 3.12+
- FastAPI
- Provider adapters behind an internal interface
- Model/provider configuration stored in database and reloadable at runtime
- All external model calls audited

Reason:

- AI behavior must be hot-configurable and testable.
- Legal QA and review need tight integration with RAG, citations, prompt versions, and audit trails.
- The AI platform is a service boundary, not a library hidden inside the contract backend.

### Worker

- `yuqei-ai-platform/services/worker`
- Python 3.12+
- Redis queue initially
- Later can evolve to Celery/RQ/Arq depending on load

Responsibilities:

- OCR and document extraction
- Knowledge indexing
- Export generation
- Reminder jobs
- AI long-running jobs

### Database

- PostgreSQL 16+
- Multiple schemas in one primary database at first:
  - `identity`
  - `contract`
  - `ai`
  - `audit`
  - `ops`
- Alembic migrations
- RLS or equivalent tenant isolation for core tenant-owned tables

Reason:

- Keeps early operations simpler than multiple databases.
- Still gives clear domain separation.
- Supports full-text search, JSONB, indexes, transactions, and mature backup tooling.

### Cache and Queue

- Redis 7+

Responsibilities:

- Cache
- Distributed locks
- Rate limiting
- Lightweight async queue
- SSE/session coordination if needed

### Object Storage

- MinIO for local and private deployment
- S3-compatible interface for future cloud migration

Responsibilities:

- Original documents
- Exported Word/PDF files
- Evidence attachments
- OCR source files
- Report artifacts

### Search

Phase 1:

- PostgreSQL full-text search and trigram indexes

Phase 2:

- Evaluate OpenSearch or Meilisearch when real data scale requires it

Reason:

- Avoids introducing a search cluster before core contract workflows are stable.

### API Contracts

- `yuqei-contract-platform/packages/contract-openapi/openapi.yaml`
- `yuqei-ai-platform/packages/ai-openapi/openapi.yaml`
- OpenAPI is the source of truth for cross-service and frontend-facing contracts.
- SDKs must align with these contracts.

### SDKs

- `yuqei-ai-sdk-python`
- `yuqei-ai-sdk-typescript` only if a TypeScript SDK becomes necessary

Rules:

- Contract backend calls AI platform through Python SDK or generated OpenAPI client.
- Frontend calls contract API, not AI platform directly except for explicitly approved admin tooling.
- No vendored SDK copies.

### Infrastructure

- Docker Compose for local development and single-node deployment.
- Docker images per service.
- Nginx reverse proxy.
- Structured logs.
- Health checks for every service.
- Backup/restore scripts from day one.

## Explicit Non-Goals

- Do not continue expanding `shared-ai-platform-java`.
- Do not continue expanding the old Python `shared-ai-platform` as production.
- Do not introduce Java into V2 unless a future ADR reverses this decision.
- Do not put contract business workflows into shared modules.
- Do not make electronic signature integration part of the initial V2 MVP.

## Consequences

Positive:

- One V2 development line.
- Final engineering boundaries are visible in the root directory from the beginning.
- Contract system and AI platform have a clear service boundary.
- SDK generation and testing become enforceable.

Tradeoffs:

- Old Java shared work will be used only as reference, not as production code.
- Some features already prototyped in old shared repositories must be reimplemented.
- Root-level project boundaries must be enforced in code review to avoid recreating a mixed shared codebase.