How hrholkar/turtle_project works
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: index.ts REST route dispatch · useQueries.ts Data query hooks · sighting.service.ts Sighting management · routes.py ML request routes
Components 27
Mobile app
- Field app
frontend/app/(tabs)/upload.tsx - Identification result
frontend/app/result.tsx - Turtle and sighting views
frontend/app/turtle/[id].tsx - Verification review
frontend/app/(tabs)/pending.tsx - Conservation statistics
frontend/app/(tabs)/stats.tsx - Data query hooks
frontend/src/hooks/useQueries.ts - API client services
frontend/src/services/index.ts
Conservation API
- REST route dispatch
backend-node/src/routes/index.ts - Sighting endpoints
backend-node/src/controllers/sighting.controller.ts - Turtle endpoints
backend-node/src/controllers/turtle.controller.ts - Review endpoints
backend-node/src/controllers/pending.controller.ts - Statistics service
backend-node/src/services/dashboard.service.ts - Sighting management
backend-node/src/services/sighting.service.ts - Turtle management
backend-node/src/services/turtle.service.ts - Verification workflow
backend-node/src/services/pending.service.ts - ML service client
backend-node/src/services/ml.service.ts
Identification service
- ML request routes
backend-ml/app/api/routes.py - Inference service
backend-ml/app/services/predict_service.py - Image preprocessing
backend-ml/app/services/preprocessing/image_processor.py - Feature extraction
backend-ml/app/services/extraction/feature_extractor.py - FAISS matching index
backend-ml/app/services/matching/faiss_index.py - Match scoring
backend-ml/app/services/similarity/scorer.py - Species and identity prediction
backend-ml/ml/predict.py
Persistent data
- MongoDB records
backend-node/src/models/Turtle.ts - Image storage adapter
backend-node/src/utils/storage.ts
Other components
- Field researcher
- Administrator
Connections 30
- Field researcher → Field app: submits image
README.md - Field app → REST route dispatch: uploads sighting
- REST route dispatch → Sighting endpoints: routes request
- Sighting endpoints → Sighting management: identifies image
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
backend-ml/app/api/routes.py - Inference service → Species and identity prediction: runs inference
backend-ml/app/services/predict_service.py - ML request routes → Feature extraction: extracts features
backend-ml/app/api/routes.py - Feature extraction → Image preprocessing: processes image
backend-ml/app/services/extraction/feature_extractor.py - Species and identity prediction → FAISS matching index: searches embeddings
README.md - Species and identity prediction → Match scoring: scores matches
README.md - Sighting management → MongoDB records: records sighting
- Sighting management → Image storage adapter: stores image
- ML request routes → Identification result: returns identification
README.md - Data query hooks → API client services: fetches data
frontend/src/hooks/useQueries.ts - API client services → REST route dispatch: calls API
README.md - REST route dispatch → Turtle endpoints: routes turtle request
- Turtle endpoints → Turtle management: manages turtles
backend-node/src/controllers/turtle.controller.ts - Turtle management → MongoDB records: reads and writes
backend-node/src/services/turtle.service.ts - Turtle management → ML service client: registers identity
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
backend-node/src/controllers/pending.controller.ts - Verification workflow → MongoDB records: updates verification
- Administrator → Verification review: reviews candidate
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