SmartClover CerviGuard

CerviGuard is a working prototype for cervical image intake, automated AI analysis, and role-based clinical review. The web console integrates content-addressed image storage, distributed case metadata, and an on-edge inference service in deployments configured with the corresponding Ratio1 services. Encryption, infrastructure resilience, authorization, and audit controls remain deployment-specific and must be verified for each operating environment.

Need

Cervical screening teams need a workflow that is:

• fast enough for routine case intake,
• secure enough for sensitive medical imagery,
• structured enough for clinician/admin collaboration and traceability.

Objective

Provide a working prototype that lets authorized users:

• authenticate with role-based access,
• upload de-identified cervical images,
• receive automated transformation-zone and lesion classifications,
• review case history and outputs with auditable metadata.

Purpose

Bridge clinical workflow and decentralized infrastructure by combining:

• R1FS for content-addressed image storage,
• CStore for distributed case/user metadata,
• an on-edge inference service for cervical analysis.

Usability and Features

This repository contains a working prototype and is being used as the software starting point for TealGuard. The source, tests, and public demonstration artifacts establish implemented workflow behavior. They do not, by themselves, establish clinical performance, production readiness, medical-device conformity, use in a relevant environment, or a technology-readiness level.

Quick Start

npm install
npm run dev

Open http://localhost:3000.

Default mock admin credentials:

• Username: admin
• Password: password

In local mock mode, state is stored under .ratio1-local-state/.

User Roles

• user (clinician): create and review own cases.
• admin: full case visibility + user management.

Core Workflow

1. Sign in.
2. Upload a cervical image (jpeg/png/webp, max 20 MB) and optional notes.
3. Case is stored with status processing, then analysis is executed.
4. Case transitions to completed or error with detailed result metadata.
5. Review results in case detail pages and dashboard summaries.

Feature Set

• Secure login/logout with JWT-backed session cookies.
• Role-gated navigation and middleware-protected routes.
• Case history list (all cases for admin, own cases for clinicians).
• Case detail view with image retrieval guardrails (caseId + ownership checks).
• AI result display for:
  • transformation-zone classification,
  • lesion classification,
  • per-class confidence distributions,
  • image metadata (dimensions/channels),
  • processor timestamp/version and error details.
• Admin console:
  • create users,
  • update role and active/inactive status,
  • reset passwords through admin reset endpoint.
• Toast notifications for UX feedback in critical actions.

Operational Notes for Users

• Upload only de-identified clinical images.
• AI outputs are decision-support signals, not standalone diagnosis.
• If services are unavailable, UI surfaces explicit warnings on affected pages.

Technical

Stack

• Next.js 16 App Router
• React 19
• TypeScript 5 (strict)
• Tailwind CSS 4
• @ratio1/edge-sdk-ts (R1FS/CStore access)
• @ratio1/cstore-auth-ts (auth/user store)
• jose (JWT), zod (validation)

High-Level Architecture

Browser UI
  -> Next.js App Router pages + API routes
    -> userService / caseService
      -> CStoreAuth (users/auth)
      -> Edge SDK (R1FS + CStore)
      -> On-edge analyzer POST /predict

Data and Processing Flow

1. /api/cases receives multipart upload.
2. Analyzer calls POST {baseUrl}/predict with a base64 payload.
3. The response is validated and mapped to an internal CaseResult.
4. If validation fails, no case or image is stored.
5. Otherwise, image bytes are encoded to base64 and sent to R1FS.
6. The completed or error case record is stored in CStore.

Important behavior:

• Current analysis path is synchronous inside case creation.
• Long inference times directly affect request latency.

Auth and Access Control

• Session cookie: cerviguard_session
• JWT: HS256, TTL from AUTH_SESSION_TTL_SECONDS (default 86400 in config)
• Middleware protects:
  • /dashboard/**
  • /cases/**
  • /admin/**
  • /login redirect behavior for already-authenticated users

Configuration (Most Relevant)

Variable	Purpose	Default/Behavior
USE_RATIO1_MOCK	Enable local mock behavior	true outside production unless overridden
LOCAL_STATE_DIR	Local mock storage directory	.ratio1-local-state
DEFAULT_ADMIN_USERNAME	Seed admin username (mock)	admin
DEFAULT_ADMIN_PASSWORD	Seed admin password (mock/bootstrap fallback)	password
SESSION_SECRET / EE_SESSION_SECRET / EDGE_SESSION_SECRET	Server-only JWT signing secret source chain	at least 32 characters and required at runtime in production; demo fallback is development-only
EE_R1FS_API_URL / R1FS_API_URL	R1FS endpoint override	optional
EE_CHAINSTORE_API_URL / CHAINSTORE_API_URL	CStore endpoint override	optional
EE_CHAINSTORE_PEERS / CHAINSTORE_PEERS	Peer list JSON array	[]
R1EN_HOST_IP	Analyzer host	localhost
API_PORT	Analyzer port	5082
CERVIGUARD_API_TIMEOUT	Analyzer timeout (ms)	250000
EE_CSTORE_AUTH_HKEY / EE_CSTORE_AUTH_SECRET	Auth store keying/secrets	required for secure non-mock auth

Additional display-only envs used by UI badges:

• Host ID: EE_HOST_ID, NEXT_PUBLIC_EE_HOST_ID, RATIO1_HOST_ID, NEXT_PUBLIC_RATIO1_HOST_ID
• Peer count display also reads: R1EN_CHAINSTORE_PEERS and corresponding NEXT_PUBLIC_* variants.

Versioning

• UI version footer reads package.json version via next.config.ts -> NEXT_PUBLIC_APP_VERSION.
• If release version changes, update package.json.

Model Availability

• Public CerviGuard model artifacts are available on Hugging Face under the smartclover organization: https://huggingface.co/smartclover.
• Model creation and training scripts live in the separate repository: https://github.com/SmartCloverAI/CerviGuardModels.
• This application repository contains the web console and integration logic, not the full model-training pipeline.

API Surface (Current)

• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me
• GET /api/cases
• POST /api/cases
• GET /api/cases/[caseId]
• GET /api/files/[cid]?caseId=...
• GET /api/users (admin)
• POST /api/users (admin create)
• PUT /api/users (self/admin change password with current password)
• PATCH /api/users (admin update role/status)
• POST /api/users/reset-password (admin reset without current password)
• PATCH /api/users/[userId]/password -> returns 501 (unsupported legacy shape)

Project Layout

src/
  app/
    (auth)/                 login experience
    (platform)/             authenticated UI (dashboard/cases/admin/profile)
    api/                    route handlers
  components/               reusable UI components/modals
  contexts/                 client-side providers (toast)
  lib/
    analysis/               analyzer API mapping and validation
    auth/                   session + auth client setup
    ratio1/                 SDK wrappers for R1FS/CStore
    services/               user/case use-cases

Security and Deployment Baseline

Before any production deployment:

1. Set server-only session/auth secrets; production requests fail closed without a session secret of at least 32 characters.
2. Set USE_RATIO1_MOCK=false.
3. Configure real R1FS/CStore endpoints.
4. Validate analyzer connectivity and timeout profile for expected workload.
5. Add deployment-level safeguards (rate limiting, monitoring, audit logging).

Known Gaps / Follow-Up Targets

• Focused authorization tests cover case ownership; broader unit, integration, and end-to-end coverage remains to be added.
• Case deletion is disabled when the configured CStore backend does not expose delete semantics.
• Case creation currently blocks on analysis completion; queue-based async orchestration is a natural next hardening step.

Citations

@misc{cerviguard_pilot,
  title        = {SmartClover CerviGuard Pilot},
  author       = {Andreea D and Cristian Bleotiu and Florian Nicula},
  year         = {2024-2026},
  howpublished = {\url{https://github.com/SmartCloverAI/CerviGuard}},
  models       = {\url{https://huggingface.co/smartclover}},
  website      = {\url{https://cerviguard.link}},
  note         = {Pilot web console for cervical image analysis and case management}
}

@article {Nyanchokae053954,
	author = {Nyanchoka, Linda and Damian, Andreea and Nyg{\r a}rd, Mari},
	title = {Understanding facilitators and barriers to follow-up after abnormal cervical cancer screening examination among women living in remote areas of Romania: a qualitative study protocol},
	volume = {12},
	number = {2},
	elocation-id = {e053954},
	year = {2022},
	doi = {10.1136/bmjopen-2021-053954},
	publisher = {British Medical Journal Publishing Group},
	issn = {2044-6055},
	URL = {https://bmjopen.bmj.com/content/12/2/e053954},
	eprint = {https://bmjopen.bmj.com/content/12/2/e053954.full.pdf},
	journal = {BMJ Open}
}

@article{ANDREASSEN201748,
title = {Controversies about cervical cancer screening: A qualitative study of Roma women's (non)participation in cervical cancer screening in Romania},
journal = {Social Science & Medicine},
volume = {183},
pages = {48-55},
year = {2017},
issn = {0277-9536},
doi = {https://doi.org/10.1016/j.socscimed.2017.04.040},
url = {https://www.sciencedirect.com/science/article/pii/S0277953617302708},
author = {Trude Andreassen and Andreea Ituand Elisabete Weiderpass and Florian Nicula and Ofelia Suteu  and Minodora Bumbu and Aida Tincu and Giske Ursin and Kåre Moen},
keywords = {Cervical cancer, Cervical cancer-screening, Roma, Romania, Participation, Controversies, Interessement, User involvement}
}