# kaitm4070/cervix-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kaitm4070/cervix-ai
- Repository: https://github.com/kaitm4070/cervix-ai

## Overview

Cérvix-AI is an academic web prototype for reviewing AI-generated cervical-image classifications, not a diagnostic system. The documented user journey is image submission, validation and preprocessing, model analysis, then display of a category, confidence and visualization; the supplied frontend excerpt shows the landing and account flow, but not an implemented upload/results screen. The backend exposes an inference interface with real-model and simulator modes. Training and evaluation are distinct ML lifecycle capabilities. API wiring and several workflow details are not shown, so those connections are omitted or marked unverified.

Main entry points: [`frontend/src/components/auth/LoginModal.tsx`](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/LoginModal.tsx) (Login form), [`frontend/src/components/auth/RegisterModal.tsx`](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/RegisterModal.tsx) (Registration form), [`frontend/src/components/auth/AuthModal.tsx`](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/AuthModal.tsx) (Auth flow), [`frontend/src/services/authService.ts`](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/services/authService.ts) (Account service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_landing["Landing page<br/>[Landing.tsx]"]
  node_app["Web app routes<br/>[App.tsx]"]
end

subgraph group_auth["Account access"]
  node_authflow["Auth flow<br/>[AuthModal.tsx]"]
  node_login["Login form<br/>[LoginModal.tsx]"]
  node_register["Registration form<br/>[RegisterModal.tsx]"]
  node_objective["Objective form<br/>[ObjetiveModal.tsx]"]
  node_fields["Form fields<br/>[Fields.tsx]"]
  node_modal["Modal shell<br/>[ModalShell.tsx]"]
  node_validators["Input validation<br/>[validators.ts]"]
  node_authservice["Account service<br/>[authService.ts]"]
  node_browserstorage[("Browser storage")]
end

subgraph group_analysis["Image analysis"]
  node_api["Python API<br/>[main.py]"]
  node_inference["Image inference<br/>[inference.py]"]
  node_transform["Image transforms<br/>[Transform.py]"]
  node_factory["Model factory<br/>[Factory.py]"]
  node_package["Current model package<br/>[package.json]"]
  node_weights["Model weights<br/>[model.pt]"]
end

subgraph group_ml["Model lifecycle"]
  node_training["Model training<br/>[Train.py]"]
  node_split["Dataset splitting<br/>[Split.py]"]
  node_dataset["Image dataset<br/>[dataset.py]"]
  node_evaluation["Model evaluation<br/>[Evaluate.py]"]
end

node_visitor(("Health professional"))

node_visitor -->|"opens"| node_landing
node_landing -->|"opens"| node_authflow
node_app -->|"routes to"| node_landing
node_authflow -->|"renders"| node_login
node_authflow -->|"renders"| node_register
node_authflow -->|"renders"| node_objective
node_login -->|"renders"| node_modal
node_register -->|"renders"| node_modal
node_login -->|"renders"| node_fields
node_register -->|"renders"| node_fields
node_login -->|"validates with"| node_validators
node_register -->|"validates with"| node_validators
node_login -->|"calls login"| node_authservice
node_register -->|"calls register"| node_authservice
node_objective -->|"saves objective"| node_authservice
node_authservice -->|"reads and writes"| node_browserstorage
node_api -.->|"may invoke"| node_inference
node_inference -->|"loads package via"| node_factory
node_inference -->|"uses evaluation transform"| node_transform
node_factory -->|"reads metadata"| node_package
node_factory -->|"loads weights"| node_weights

click node_landing "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/pages/Landing.tsx"
click node_app "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/App.tsx"
click node_authflow "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/AuthModal.tsx"
click node_login "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/LoginModal.tsx"
click node_register "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/RegisterModal.tsx"
click node_objective "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/ObjetiveModal.tsx"
click node_fields "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/Fields.tsx"
click node_modal "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/ModalShell.tsx"
click node_validators "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/utils/validators.ts"
click node_authservice "https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/services/authService.ts"
click node_api "https://github.com/kaitm4070/cervix-ai/blob/main/src/api/main.py"
click node_inference "https://github.com/kaitm4070/cervix-ai/blob/main/src/analysis/inference.py"
click node_transform "https://github.com/kaitm4070/cervix-ai/blob/main/src/preprocessing/Transform.py"
click node_factory "https://github.com/kaitm4070/cervix-ai/blob/main/src/models/Factory.py"
click node_package "https://github.com/kaitm4070/cervix-ai/blob/main/models/vigente/package.json"
click node_weights "https://github.com/kaitm4070/cervix-ai/blob/main/models/vigente/model.pt"
click node_training "https://github.com/kaitm4070/cervix-ai/blob/main/src/training/Train.py"
click node_split "https://github.com/kaitm4070/cervix-ai/blob/main/src/training/Split.py"
click node_dataset "https://github.com/kaitm4070/cervix-ai/blob/main/src/training/dataset.py"
click node_evaluation "https://github.com/kaitm4070/cervix-ai/blob/main/src/evaluation/Evaluate.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_landing,node_app toneBlue
class node_authflow,node_login,node_register,node_objective,node_fields,node_modal,node_validators,node_authservice,node_browserstorage toneAmber
class node_api,node_inference,node_transform,node_factory,node_package,node_weights toneMint
class node_training,node_split,node_dataset,node_evaluation toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Landing page](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/pages/Landing.tsx): `frontend/src/pages/Landing.tsx`
- [Web app routes](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Account access

- [Auth flow](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/AuthModal.tsx): `frontend/src/components/auth/AuthModal.tsx`
- [Login form](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/LoginModal.tsx): `frontend/src/components/auth/LoginModal.tsx`
- [Registration form](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/RegisterModal.tsx): `frontend/src/components/auth/RegisterModal.tsx`
- [Objective form](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/ObjetiveModal.tsx): `frontend/src/components/auth/ObjetiveModal.tsx`
- [Form fields](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/Fields.tsx): `frontend/src/components/auth/Fields.tsx`
- [Modal shell](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/components/auth/ModalShell.tsx): `frontend/src/components/auth/ModalShell.tsx`
- [Input validation](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/utils/validators.ts): `frontend/src/utils/validators.ts`
- [Account service](https://github.com/kaitm4070/cervix-ai/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- **Browser storage**

### Image analysis

- [Python API](https://github.com/kaitm4070/cervix-ai/blob/main/src/api/main.py): `src/api/main.py`
- [Image inference](https://github.com/kaitm4070/cervix-ai/blob/main/src/analysis/inference.py): `src/analysis/inference.py`
- [Image transforms](https://github.com/kaitm4070/cervix-ai/blob/main/src/preprocessing/Transform.py): `src/preprocessing/Transform.py`
- [Model factory](https://github.com/kaitm4070/cervix-ai/blob/main/src/models/Factory.py): `src/models/Factory.py`
- [Current model package](https://github.com/kaitm4070/cervix-ai/blob/main/models/vigente/package.json): `models/vigente/package.json`
- [Model weights](https://github.com/kaitm4070/cervix-ai/blob/main/models/vigente/model.pt): `models/vigente/model.pt`

### Model lifecycle

- [Model training](https://github.com/kaitm4070/cervix-ai/blob/main/src/training/Train.py): `src/training/Train.py`
- [Dataset splitting](https://github.com/kaitm4070/cervix-ai/blob/main/src/training/Split.py): `src/training/Split.py`
- [Image dataset](https://github.com/kaitm4070/cervix-ai/blob/main/src/training/dataset.py): `src/training/dataset.py`
- [Model evaluation](https://github.com/kaitm4070/cervix-ai/blob/main/src/evaluation/Evaluate.py): `src/evaluation/Evaluate.py`

### Other components

- **Health professional**

## Connections

- Health professional → Landing page: opens (evidence: `frontend/src/pages/Landing.tsx`)
- Landing page → Auth flow: opens (evidence: `frontend/src/pages/Landing.tsx`)
- Web app routes → Landing page: routes to (evidence: `frontend/src/App.tsx`)
- Auth flow → Login form: renders (evidence: `frontend/src/components/auth/AuthModal.tsx`)
- Auth flow → Registration form: renders (evidence: `frontend/src/components/auth/AuthModal.tsx`)
- Auth flow → Objective form: renders (evidence: `frontend/src/components/auth/AuthModal.tsx`)
- Login form → Modal shell: renders (evidence: `frontend/src/components/auth/LoginModal.tsx`)
- Registration form → Modal shell: renders (evidence: `frontend/src/components/auth/RegisterModal.tsx`)
- Login form → Form fields: renders (evidence: `frontend/src/components/auth/LoginModal.tsx`)
- Registration form → Form fields: renders (evidence: `frontend/src/components/auth/RegisterModal.tsx`)
- Login form → Input validation: validates with (evidence: `frontend/src/components/auth/LoginModal.tsx`)
- Registration form → Input validation: validates with (evidence: `frontend/src/components/auth/RegisterModal.tsx`)
- Login form → Account service: calls login (evidence: `frontend/src/components/auth/LoginModal.tsx`)
- Registration form → Account service: calls register (evidence: `frontend/src/components/auth/RegisterModal.tsx`)
- Objective form → Account service: saves objective (evidence: `frontend/src/components/auth/AuthModal.tsx`)
- Account service → Browser storage: reads and writes (evidence: `frontend/src/services/authService.ts`)
- Python API → Image inference: may invoke
- Image inference → Model factory: loads package via (evidence: `src/analysis/inference.py`)
- Image inference → Image transforms: uses evaluation transform (evidence: `src/analysis/inference.py`)
- Model factory → Current model package: reads metadata (evidence: `src/models/Factory.py`)
- Model factory → Model weights: loads weights (evidence: `src/models/Factory.py`)