# anhtun1467/cccd-ai-service architecture

> Architecture diagram of the GitHub repository anhtun1467/cccd-ai-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anhtun1467/cccd-ai-service
- Repository: https://github.com/anhtun1467/cccd-ai-service

## Overview

CCCD AI Service is a FastAPI application for recognizing Vietnamese identity cards and performing 1:1 face verification. The primary workflow uploads a card image, detects and rectifies the card, extracts and validates identity fields, then returns JSON and retains card/portrait data in a short-lived session. A later selfie or camera capture can reuse that session for face-quality checks and similarity matching. The README documents these stages and thresholds; the sampled source confirms the application router setup and OCR pipeline behavior, but does not expose all endpoint-to-service calls.

Main entry points: [`app/services/ocr_pipeline.py`](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/ocr_pipeline.py) (OCR pipeline), [`app/services/face_verification_pipeline.py`](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/face_verification_pipeline.py) (Face pipeline), [`app/modules/card_detection/detector.py`](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/detector.py) (Card detection), [`app/api/face_verification.py`](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/api/face_verification.py) (Face endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_ocr_api["OCR endpoint<br/>[ocr.py]"]
  node_ocr_flow["OCR pipeline<br/>[ocr_pipeline.py]"]
  node_face_api["Face endpoints"]
  node_face_flow["Face pipeline"]
end

subgraph group_card["Card image processing"]
  node_card_detect["Card detection<br/>[detector.py]"]
  node_card_transform["Perspective transform"]
  node_card_enhance["Image enhancement<br/>[image_enhancer.py]"]
end

subgraph group_ocr["Identity extraction"]
  node_ocr_service["OCR service<br/>[service.py]"]
  node_ocr_engine["EasyOCR engine<br/>[easyocr_engine.py]"]
  node_field_ocr["Field OCR"]
  node_text_parse["Parse and normalize<br/>[regex_parser.py]"]
  node_field_validate["Field validation<br/>[validator.py]"]
  node_qr_decode["QR decode and fuse<br/>[qr_ocr_fuser.py]"]
end

subgraph group_face["Face verification"]
  node_session_store["Face sessions"]
  node_portrait["Portrait extraction"]
  node_face_quality["Face quality and detection<br/>[quality.py]"]
  node_face_embedding["Face embeddings<br/>[embedding.py]"]
  node_face_match["Similarity matching<br/>[matcher.py]"]
end

node_client(("Client"))
node_capture(("Selfie capture"))
node_response["JSON result"]

node_client -->|"uploads card"| node_ocr_api
node_ocr_api -->|"starts OCR"| node_ocr_flow
node_ocr_flow -->|"detects card"| node_card_detect
node_card_detect -->|"rectifies card"| node_card_transform
node_card_detect -->|"enhances image"| node_card_enhance
node_ocr_flow -->|"runs OCR"| node_ocr_service
node_ocr_service -->|"recognizes text"| node_ocr_engine
node_ocr_flow -->|"extracts fields"| node_field_ocr
node_ocr_flow -->|"parses text"| node_text_parse
node_ocr_flow -->|"validates fields"| node_field_validate
node_ocr_flow -->|"fuses QR data"| node_qr_decode
node_ocr_flow -->|"extracts portrait"| node_portrait
node_ocr_flow -->|"retains OCR session"| node_session_store
node_ocr_flow -->|"returns OCR result"| node_response
node_capture -->|"submits selfie"| node_face_api
node_client -->|"checks session"| node_face_api
node_face_api -->|"starts verification"| node_face_flow
node_face_flow -->|"loads session"| node_session_store
node_face_flow -->|"uses portrait"| node_portrait
node_face_flow -->|"checks face"| node_face_quality
node_face_flow -->|"computes embeddings"| node_face_embedding
node_face_flow -->|"compares faces"| node_face_match
node_face_flow -->|"returns decision"| node_response

click node_ocr_api "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/api/ocr.py"
click node_ocr_flow "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/ocr_pipeline.py"
click node_face_api "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/api/face_verification.py"
click node_face_flow "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/face_verification_pipeline.py"
click node_card_detect "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/detector.py"
click node_card_transform "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/perspective_transformer.py"
click node_card_enhance "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/image_enhancer.py"
click node_ocr_service "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/service.py"
click node_ocr_engine "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/easyocr_engine.py"
click node_field_ocr "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/field_ocr_service.py"
click node_text_parse "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/parser/regex_parser.py"
click node_field_validate "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/validator.py"
click node_qr_decode "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/qr/qr_ocr_fuser.py"
click node_session_store "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/face_session_store.py"
click node_portrait "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/portrait_extractor.py"
click node_face_quality "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/quality.py"
click node_face_embedding "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/embedding.py"
click node_face_match "https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/matcher.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ocr_api,node_ocr_flow,node_face_api,node_face_flow,node_client toneBlue
class node_card_detect,node_card_transform,node_card_enhance toneAmber
class node_ocr_service,node_ocr_engine,node_field_ocr,node_text_parse,node_field_validate,node_qr_decode toneMint
class node_session_store,node_portrait,node_face_quality,node_face_embedding,node_face_match toneRose
class node_capture,node_response toneIndigo
```

## Components

### API and orchestration

- [OCR endpoint](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/api/ocr.py): `app/api/ocr.py`
- [OCR pipeline](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/ocr_pipeline.py): `app/services/ocr_pipeline.py`
- [Face endpoints](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/api/face_verification.py): `app/api/face_verification.py`
- [Face pipeline](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/face_verification_pipeline.py): `app/services/face_verification_pipeline.py`

### Card image processing

- [Card detection](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/detector.py): `app/modules/card_detection/detector.py`
- [Perspective transform](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/perspective_transformer.py): `app/modules/card_detection/perspective_transformer.py`
- [Image enhancement](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/card_detection/image_enhancer.py): `app/modules/card_detection/image_enhancer.py`

### Identity extraction

- [OCR service](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/service.py): `app/modules/ocr/service.py`
- [EasyOCR engine](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/easyocr_engine.py): `app/modules/ocr/easyocr_engine.py`
- [Field OCR](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/field_ocr_service.py): `app/modules/ocr/field_ocr_service.py`
- [Parse and normalize](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/parser/regex_parser.py): `app/modules/ocr/parser/regex_parser.py`
- [Field validation](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/ocr/validator.py): `app/modules/ocr/validator.py`
- [QR decode and fuse](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/qr/qr_ocr_fuser.py): `app/modules/qr/qr_ocr_fuser.py`

### Face verification

- [Face sessions](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/services/face_session_store.py): `app/services/face_session_store.py`
- [Portrait extraction](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/portrait_extractor.py): `app/modules/face_verification/portrait_extractor.py`
- [Face quality and detection](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/quality.py): `app/modules/face_verification/quality.py`
- [Face embeddings](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/embedding.py): `app/modules/face_verification/embedding.py`
- [Similarity matching](https://github.com/anhtun1467/cccd-ai-service/blob/main/app/modules/face_verification/matcher.py): `app/modules/face_verification/matcher.py`

### Other components

- **Client**
- **Selfie capture**
- **JSON result**

## Connections

- Client → OCR endpoint: uploads card
- OCR endpoint → OCR pipeline: starts OCR
- OCR pipeline → Card detection: detects card
- Card detection → Perspective transform: rectifies card
- Card detection → Image enhancement: enhances image
- OCR pipeline → OCR service: runs OCR
- OCR service → EasyOCR engine: recognizes text
- OCR pipeline → Field OCR: extracts fields
- OCR pipeline → Parse and normalize: parses text
- OCR pipeline → Field validation: validates fields
- OCR pipeline → QR decode and fuse: fuses QR data
- OCR pipeline → Portrait extraction: extracts portrait
- OCR pipeline → Face sessions: retains OCR session
- OCR pipeline → JSON result: returns OCR result
- Selfie capture → Face endpoints: submits selfie
- Client → Face endpoints: checks session
- Face endpoints → Face pipeline: starts verification
- Face pipeline → Face sessions: loads session
- Face pipeline → Portrait extraction: uses portrait
- Face pipeline → Face quality and detection: checks face
- Face pipeline → Face embeddings: computes embeddings
- Face pipeline → Similarity matching: compares faces
- Face pipeline → JSON result: returns decision