# hrholkar/turtle_project architecture

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

- Interactive diagram: https://gitdiagram.com/hrholkar/turtle_project
- Repository: https://github.com/hrholkar/turtle_project

## Overview

TurtleTrack is a mobile-first sea-turtle re-identification and conservation platform. Researchers submit field images and sighting metadata; the Node API coordinates identification with the Python ML service, then returns a match or a new-turtle candidate for review. Researchers can browse turtle and sighting histories, while administrators resolve pending verifications and consult conservation statistics. The graph preserves the documented preprocessing, embedding, matching, and scoring stages. Some UI-to-API and service-to-service links are documented at product level; unsampled implementation details are not inferred.

Main entry points: [`backend-node/src/routes/index.ts`](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/routes/index.ts) (REST route dispatch), [`frontend/src/hooks/useQueries.ts`](https://github.com/hrholkar/turtle_project/blob/main/frontend/src/hooks/useQueries.ts) (Data query hooks), [`backend-node/src/services/sighting.service.ts`](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/sighting.service.ts) (Sighting management), [`backend-ml/app/api/routes.py`](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/api/routes.py) (ML request routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_app["Field app<br/>[upload.tsx]"]
  node_result_ui["Identification result<br/>[result.tsx]"]
  node_history_ui["Turtle and sighting views<br/>[&#91;id&#93;.tsx]"]
  node_review_ui["Verification review<br/>[pending.tsx]"]
  node_stats_ui["Conservation statistics<br/>[stats.tsx]"]
  node_query_hooks["Data query hooks<br/>[useQueries.ts]"]
  node_client_services["API client services<br/>[index.ts]"]
end

subgraph group_api["Conservation API"]
  node_node_routes["REST route dispatch<br/>[index.ts]"]
  node_sighting_controller["Sighting endpoints"]
  node_turtle_controller["Turtle endpoints"]
  node_pending_controller["Review endpoints"]
  node_dashboard_service["Statistics service"]
  node_sighting_service["Sighting management"]
  node_turtle_service["Turtle management<br/>[turtle.service.ts]"]
  node_pending_service["Verification workflow<br/>[pending.service.ts]"]
  node_ml_client["ML service client<br/>[ml.service.ts]"]
end

subgraph group_ml["Identification service"]
  node_ml_routes["ML request routes<br/>[routes.py]"]
  node_predict_service["Inference service<br/>[predict_service.py]"]
  node_image_preprocess["Image preprocessing<br/>[image_processor.py]"]
  node_feature_extractor["Feature extraction"]
  node_faiss_index[("FAISS matching index<br/>[faiss_index.py]")]
  node_similarity_scorer["Match scoring<br/>[scorer.py]"]
  node_ml_predict["Species and identity prediction<br/>[predict.py]"]
end

subgraph group_data["Persistent data"]
  node_mongo[("MongoDB records<br/>[Turtle.ts]")]
  node_image_storage["Image storage adapter<br/>[storage.ts]"]
end

node_researcher(("Field researcher"))
node_admin(("Administrator"))

node_researcher -->|"submits image"| node_mobile_app
node_mobile_app -.->|"uploads sighting"| node_node_routes
node_node_routes -->|"routes request"| node_sighting_controller
node_sighting_controller -->|"identifies image"| node_sighting_service
node_sighting_service -.->|"requests identification"| node_ml_client
node_ml_client -.->|"sends image"| node_ml_routes
node_ml_routes -->|"delegates prediction"| node_predict_service
node_predict_service -->|"runs inference"| node_ml_predict
node_ml_routes -->|"extracts features"| node_feature_extractor
node_feature_extractor -->|"processes image"| node_image_preprocess
node_ml_predict -.->|"searches embeddings"| node_faiss_index
node_ml_predict -.->|"scores matches"| node_similarity_scorer
node_sighting_service -.->|"records sighting"| node_mongo
node_sighting_service -.->|"stores image"| node_image_storage
node_ml_routes -.->|"returns identification"| node_result_ui
node_query_hooks -->|"fetches data"| node_client_services
node_client_services -.->|"calls API"| node_node_routes
node_node_routes -->|"routes turtle request"| node_turtle_controller
node_turtle_controller -->|"manages turtles"| node_turtle_service
node_turtle_service -->|"reads and writes"| node_mongo
node_turtle_service -->|"registers identity"| node_ml_client
node_history_ui -.->|"loads history"| node_query_hooks
node_node_routes -->|"routes review request"| node_pending_controller
node_pending_controller -->|"resolves review"| node_pending_service
node_pending_service -.->|"updates verification"| node_mongo
node_admin -->|"reviews candidate"| node_review_ui
node_review_ui -.->|"loads review queue"| node_query_hooks
node_node_routes -.->|"serves statistics"| node_dashboard_service
node_stats_ui -.->|"loads statistics"| node_query_hooks
node_result_ui -.->|"loads match details"| node_query_hooks

click node_mobile_app "https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/upload.tsx"
click node_result_ui "https://github.com/hrholkar/turtle_project/blob/main/frontend/app/result.tsx"
click node_history_ui "https://github.com/hrholkar/turtle_project/blob/main/frontend/app/turtle/%5Bid%5D.tsx"
click node_review_ui "https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/pending.tsx"
click node_stats_ui "https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/stats.tsx"
click node_query_hooks "https://github.com/hrholkar/turtle_project/blob/main/frontend/src/hooks/useQueries.ts"
click node_client_services "https://github.com/hrholkar/turtle_project/blob/main/frontend/src/services/index.ts"
click node_node_routes "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/routes/index.ts"
click node_sighting_controller "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/sighting.controller.ts"
click node_turtle_controller "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/turtle.controller.ts"
click node_pending_controller "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/pending.controller.ts"
click node_dashboard_service "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/dashboard.service.ts"
click node_sighting_service "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/sighting.service.ts"
click node_turtle_service "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/turtle.service.ts"
click node_pending_service "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/pending.service.ts"
click node_ml_client "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/ml.service.ts"
click node_mongo "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/models/Turtle.ts"
click node_image_storage "https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/utils/storage.ts"
click node_ml_routes "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/api/routes.py"
click node_predict_service "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/predict_service.py"
click node_image_preprocess "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/preprocessing/image_processor.py"
click node_feature_extractor "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/extraction/feature_extractor.py"
click node_faiss_index "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/matching/faiss_index.py"
click node_similarity_scorer "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/similarity/scorer.py"
click node_ml_predict "https://github.com/hrholkar/turtle_project/blob/main/backend-ml/ml/predict.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_mobile_app,node_result_ui,node_history_ui,node_review_ui,node_stats_ui,node_query_hooks,node_client_services toneBlue
class node_node_routes,node_sighting_controller,node_turtle_controller,node_pending_controller,node_dashboard_service,node_sighting_service,node_turtle_service,node_pending_service,node_ml_client toneAmber
class node_ml_routes,node_predict_service,node_image_preprocess,node_feature_extractor,node_faiss_index,node_similarity_scorer,node_ml_predict toneMint
class node_mongo,node_image_storage toneRose
class node_researcher,node_admin toneIndigo
```

## Components

### Mobile app

- [Field app](https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/upload.tsx): `frontend/app/(tabs)/upload.tsx`
- [Identification result](https://github.com/hrholkar/turtle_project/blob/main/frontend/app/result.tsx): `frontend/app/result.tsx`
- [Turtle and sighting views](https://github.com/hrholkar/turtle_project/blob/main/frontend/app/turtle/%5Bid%5D.tsx): `frontend/app/turtle/[id].tsx`
- [Verification review](https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/pending.tsx): `frontend/app/(tabs)/pending.tsx`
- [Conservation statistics](https://github.com/hrholkar/turtle_project/blob/main/frontend/app/(tabs)/stats.tsx): `frontend/app/(tabs)/stats.tsx`
- [Data query hooks](https://github.com/hrholkar/turtle_project/blob/main/frontend/src/hooks/useQueries.ts): `frontend/src/hooks/useQueries.ts`
- [API client services](https://github.com/hrholkar/turtle_project/blob/main/frontend/src/services/index.ts): `frontend/src/services/index.ts`

### Conservation API

- [REST route dispatch](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/routes/index.ts): `backend-node/src/routes/index.ts`
- [Sighting endpoints](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/sighting.controller.ts): `backend-node/src/controllers/sighting.controller.ts`
- [Turtle endpoints](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/turtle.controller.ts): `backend-node/src/controllers/turtle.controller.ts`
- [Review endpoints](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/controllers/pending.controller.ts): `backend-node/src/controllers/pending.controller.ts`
- [Statistics service](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/dashboard.service.ts): `backend-node/src/services/dashboard.service.ts`
- [Sighting management](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/sighting.service.ts): `backend-node/src/services/sighting.service.ts`
- [Turtle management](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/turtle.service.ts): `backend-node/src/services/turtle.service.ts`
- [Verification workflow](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/pending.service.ts): `backend-node/src/services/pending.service.ts`
- [ML service client](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/services/ml.service.ts): `backend-node/src/services/ml.service.ts`

### Identification service

- [ML request routes](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/api/routes.py): `backend-ml/app/api/routes.py`
- [Inference service](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/predict_service.py): `backend-ml/app/services/predict_service.py`
- [Image preprocessing](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/preprocessing/image_processor.py): `backend-ml/app/services/preprocessing/image_processor.py`
- [Feature extraction](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/extraction/feature_extractor.py): `backend-ml/app/services/extraction/feature_extractor.py`
- [FAISS matching index](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/matching/faiss_index.py): `backend-ml/app/services/matching/faiss_index.py`
- [Match scoring](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/app/services/similarity/scorer.py): `backend-ml/app/services/similarity/scorer.py`
- [Species and identity prediction](https://github.com/hrholkar/turtle_project/blob/main/backend-ml/ml/predict.py): `backend-ml/ml/predict.py`

### Persistent data

- [MongoDB records](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/models/Turtle.ts): `backend-node/src/models/Turtle.ts`
- [Image storage adapter](https://github.com/hrholkar/turtle_project/blob/main/backend-node/src/utils/storage.ts): `backend-node/src/utils/storage.ts`

### Other components

- **Field researcher**
- **Administrator**

## Connections

- Field researcher → Field app: submits image (evidence: `README.md`)
- Field app → REST route dispatch: uploads sighting
- REST route dispatch → Sighting endpoints: routes request
- Sighting endpoints → Sighting management: identifies image (evidence: `backend-node/src/controllers/sighting.controller.ts`)
- Sighting management → ML service client: requests identification
- ML service client → ML request routes: sends image
- ML request routes → Inference service: delegates prediction (evidence: `backend-ml/app/api/routes.py`)
- Inference service → Species and identity prediction: runs inference (evidence: `backend-ml/app/services/predict_service.py`)
- ML request routes → Feature extraction: extracts features (evidence: `backend-ml/app/api/routes.py`)
- Feature extraction → Image preprocessing: processes image (evidence: `backend-ml/app/services/extraction/feature_extractor.py`)
- Species and identity prediction → FAISS matching index: searches embeddings (evidence: `README.md`)
- Species and identity prediction → Match scoring: scores matches (evidence: `README.md`)
- Sighting management → MongoDB records: records sighting
- Sighting management → Image storage adapter: stores image
- ML request routes → Identification result: returns identification (evidence: `README.md`)
- Data query hooks → API client services: fetches data (evidence: `frontend/src/hooks/useQueries.ts`)
- API client services → REST route dispatch: calls API (evidence: `README.md`)
- REST route dispatch → Turtle endpoints: routes turtle request
- Turtle endpoints → Turtle management: manages turtles (evidence: `backend-node/src/controllers/turtle.controller.ts`)
- Turtle management → MongoDB records: reads and writes (evidence: `backend-node/src/services/turtle.service.ts`)
- Turtle management → ML service client: registers identity (evidence: `backend-node/src/services/turtle.service.ts`)
- Turtle and sighting views → Data query hooks: loads history
- REST route dispatch → Review endpoints: routes review request
- Review endpoints → Verification workflow: resolves review (evidence: `backend-node/src/controllers/pending.controller.ts`)
- Verification workflow → MongoDB records: updates verification
- Administrator → Verification review: reviews candidate (evidence: `README.md`)
- Verification review → Data query hooks: loads review queue
- REST route dispatch → Statistics service: serves statistics
- Conservation statistics → Data query hooks: loads statistics
- Identification result → Data query hooks: loads match details
