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.