bhavjeetsingh/contractiq

1. System shape

ContractIQ is a FastAPI-based document intelligence service with a thin HTML frontend. The browser-facing layer lives in templates/ and static/, while almost all business logic sits under src/. The app is centered on contract PDFs and exposes analysis, comparison, and chat-style Q&A workflows.

2. Request entry point

api/main.py is the main orchestration layer. It wires routes, file upload handling, template rendering, and health checks. From an architecture standpoint, this is the boundary between HTTP requests and the internal document-processing pipelines.

3. Document ingestion boundary

src/document_ingestion/ handles the first stage of every document workflow: saving uploaded files, reading PDF content page by page, and preparing content for downstream processing. This is the shared entry path for analysis, comparison, and chat indexing, so it acts as the normalization layer for all document inputs.

4. Analysis pipeline

src/document_analyzer/data_analysis.py is responsible for extracting structured contract intelligence such as metadata, summary, sentiment/tone, and obligations. It uses LLM prompting plus structured output models from model/models.py, so the output is not just free text but schema-shaped data suitable for API responses.

5. Comparison pipeline

src/document_compare/document_comparator.py compares two document versions, likely page-by-page or section-by-section, and asks the model to identify differences and meaningful changes. This is a separate pipeline from analysis because it consumes two inputs and produces a delta-oriented result rather than a single-document summary.

6. Conversational RAG subsystem

src/document_chat/ implements the multi-document Q&A flow. retrieval.py and hybrid_retrieval.py provide retrieval logic, while sse_streaming.py suggests optional streaming response support. The README indicates a session-scoped FAISS index, so chat is built around document indexing per session followed by retrieval-augmented generation on query.

7. LLM and prompt layer

The model-agnostic orchestration is concentrated in prompt/prompt_library.py, utils/model_loader.py, and config/config.yaml. This layer configures the actual model providers described in the README: Groq-hosted LLMs for generation and Google Gemini embeddings for vectorization. LangChain is the integration framework connecting prompts, parsers, and model calls.

8. Structured outputs and domain schemas

model/models.py defines the Pydantic schemas that constrain responses from analysis and related workflows. This is an important architectural boundary: unstructured LLM output is forced into typed application models before it reaches API consumers.

9. Cross-cutting platform services

Logging, exceptions, and rate control are implemented as shared infrastructure rather than feature code. logger/custom_logger.py provides structured JSON logs, exception/custom_exception.py captures rich traceback context, and utils/rate_limiter.py suggests request throttling support. These apply across routes rather than inside one business feature.

10. Session, auth, and caching hooks

src/auth/jwt_handler.py and src/cache/redis_cache.py indicate planned or partial supporting services for identity and response caching. Even if not central today, they define architectural seams for future user isolation, protected routes, and reduced LLM latency.

11. Evaluation and tracing

src/eval/ragas_evaluator.py, run_eval.py, and utils/langsmith_tracer.py form the quality/observability lane. This is separate from production request handling and is used to score or inspect retrieval-generation quality, which matters for a contract-analysis product where answer fidelity is critical.

12. Deployment and runtime

Production deployment is containerized with Docker and described in infrastructure/document-portal-cf.yaml. The repo also includes AWS ECS Fargate, ECR, Secrets Manager, and CloudWatch integration, so the runtime boundary is a managed container service with externalized secret management and centralized logs. GitHub Actions in .github/workflows/ci.yaml handles CI/CD.

13. Frontend and UX boundary

The HTML templates (templates/index.html, templates/login.html) and static/style.css suggest a server-rendered UI rather than a separate SPA. The frontend’s role is primarily to submit PDFs, render results, and drive chat/comparison workflows against the FastAPI backend.

14. Testing and validation

tests/test_routes.py and tests/test_unit_cases.py verify both API behavior and core utility logic. This shows the repo treats route correctness and internal processing as separate test surfaces, which is useful when diagramming trust boundaries around HTTP input and document-processing internals.