A full-stack retail photo capture platform with a Flutter mobile client and Node/Express API, built around field capture reliability, project-based organization, geolocation-assisted workflows, and scalable direct-to-storage uploads.
Executive Summary
Core Workflow
Mobile photo capture with project + store context and library management
Storage Pattern
MongoDB for metadata, Cloudflare R2 for binaries via direct upload
Field UX
GPS-assisted store detection with manual fallback and retry-friendly uploads
Delivery Signal
Consultancy-led technical implementation with cloud-ready API operations posture
Overview
The Problem
Retail/FMCG field teams need a reliable way to capture store photos with project context, location awareness, and traceable metadata, but upload reliability and field ergonomics are often weak in generic tools.
The Opportunity
Build a mobile-first capture platform with a scalable upload pipeline, portfolio-style project organization, geolocation-assisted store selection, and clear ownership boundaries in the API.
My Role
Technical implementation lead / consultant: managing architecture decisions and delivery across the Flutter mobile client, Node/Express API, storage integration, and operational deployment readiness.
Platform Shape
Flutter mobile app + Node/Express API + MongoDB Atlas for metadata + Cloudflare R2 for binaries, with direct-to-object-storage uploads and environment-driven deployment configuration.
Domain Model Snapshot
Projects
User-owned project records with brand/category/store/notes metadata and archive/restore lifecycle controls.
Photos
Photos carry upload state and metadata, support project tagging/un-tagging after capture, and power previews and history views.
Stores + Location
GPS-assisted store suggestion with manual override fallback, plus nearest-store and text search endpoints for practical field use.
Ownership + Access
Auth-sensitive operations enforce resource ownership checks, with role middleware available for admin-only route protection.
Architecture Decisions
The platform is intentionally optimized around the realities of field capture: large image uploads, inconsistent location signals, auth-sensitive data, and the need for direct media handling patterns that scale cleanly.
Core Runtime Flows
Why These Decisions
Split metadata storage and binary storage
Why: Photo binaries and domain metadata have very different scaling and access patterns.
Impact: MongoDB Atlas stores domain metadata while Cloudflare R2 handles media objects, keeping the API focused on orchestration and authorization.
Three-step upload workflow (init-upload -> direct upload -> complete-upload)
Why: The backend should not sit in the hot path for large file transfer.
Impact: Scalable uploads, reduced server bandwidth pressure, and cleaner status transitions for upload lifecycle tracking.
GeoJSON + geospatial indexes for store workflows
Why: Nearest-store suggestions are a core field UX enhancement, not an afterthought.
Impact: Fast nearest-store lookups and a clearer path to richer location-aware features later.
Provider/state + service-layer client architecture
Why: Mobile flows span auth, location, projects, photos, and uploads and need separation of concerns.
Impact: Cleaner feature boundaries in Flutter and easier maintenance/testing of operational flows.
Environment-first, cloud-ready backend setup
Why: The platform needs to be deployable early with predictable operational behavior.
Impact: Render-ready config, health/status probes, structured logging, and environment-driven secrets/rate limits.
Offline-tolerant UX touches before full offline architecture
Why: Field work needs resilience even before a full offline sync engine exists.
Impact: Local capture history and retry-capable uploads improve usability without overbuilding the POC/product stage.
API / Backend
The backend coordinates auth, ownership, project and photo metadata, geospatial store lookup, and the pre-signed upload lifecycle while keeping file transfer out of the API request path.
Registration, login, session restore bootstrap support, profile updates, forgot/reset password, and JWT bearer auth form the account foundation.
Projects support create/edit/archive/restore/delete with metadata fields used to organize capture and library workflows.
Photo metadata powers list/detail views, sorting/filtering, project previews, store history, and post-upload project assignment changes.
API orchestrates upload initialization/finalization while clients upload directly to Cloudflare R2 via pre-signed URLs.
Store collection uses 2dsphere and text indexes to support nearest-store lookup and text search endpoints for field workflows.
Express stack includes Helmet, CORS allowlist, auth/global rate limiting, proxy-aware IP handling, and centralized 404/500 error middleware with structured logs.
Environment-driven configuration and health/status probes make the API deployable on Render with visible service state.
Mobile App (Flutter)
The Flutter client is where product value is realized in the field: capture, project tagging, store detection, browsing, sorting, and sharing all need to feel fast and forgiving under real usage conditions.
Bottom navigation app shell organizes Home, Library, Capture, Projects, and Profile flows with service-oriented feature boundaries.
Capture flow combines camera usage, required project selection, GPS-assisted store detection, and manual override to support real-world field behavior.
Users can browse uploaded photos, filter by store/project, sort oldest/newest, open detail views, and update project assignment metadata after upload.
Remote images can be downloaded to temporary storage and shared through the native OS share sheet for downstream reporting and collaboration.
Secure token storage plus shared_preferences-backed local UX state improves session continuity and capture/upload resilience.
Security, Reliability & Ops
The API stack and deployment model are shaped for practical production readiness: health probes, structured logs, environment config, rate limits, and centralized error handling are already in place during active implementation.
Deployment Model
Cloud-ready backend targeting Render with health/status probes, environment-driven config, and structured logging.
Config Strategy
Secrets and runtime behavior are environment-first: JWT, DB, CORS, rate limits, and R2 credentials are all externally configured.
Observability
Centralized error handling and structured JSON logs support debugging across HTTP and app-level events.
Security Controls
Helmet, CORS allowlist, auth/global rate limiting, proxy-aware IP handling, and ownership checks across auth-sensitive operations.
Tradeoffs & Constraints
The current implementation already has solid platform decisions. Most remaining issues are tuning and API/UX alignment improvements, which is exactly what you want to see at this stage.
Client/server list alignment still maturing
Rationale: The client sends limit/sort params for photo listing, but the backend currently applies a fixed server-side limit/sort behavior.
Tradeoff: Stable backend behavior now, but API/consumer parameter alignment is an obvious next iteration.
Nearby-store radius tuning is intentionally interim
Rationale: The nearby-store endpoint currently uses a temporary max-distance value (25000) instead of the requested radius.
Tradeoff: Fast geospatial feature delivery now, with clear follow-up tuning/parameter fidelity work later.
Hard-coded widget styling in parts of the mobile UI
Rationale: Some component-level styling is hard-coded while the app overall uses a Material 3 seed-based theme.
Tradeoff: Faster UI delivery during active implementation, but a clear theming consistency cleanup remains.
Mobile-first product surface vs broader back-office tooling
Rationale: The core value is field capture and library workflows, so implementation effort favors mobile-first operational flows.
Tradeoff: Strong field UX early, while deeper analytics/admin tooling can evolve later as usage patterns stabilize.
Outcomes / Metrics
Public metrics are not listed here, but the implementation already demonstrates scalable upload patterns, field-ready UX decisions, and an operationally sensible backend foundation.
Outcomes / Delivery Signals
Quality / Maturity Signals
What I'd Improve Next
The strongest next steps are already visible in the current product: endpoint alignment, geospatial tuning, theming consistency, and deeper testing/telemetry around upload and field capture behavior.
Align list-photos endpoint behavior with client-supplied sort/limit parameters.
Replace temporary nearby-store max distance tuning with request-driven radius handling and better calibration.
Consolidate hard-coded widget colors into the Material 3 seed/theme system for consistency.
Expand analytics/admin surfaces if usage patterns justify deeper reporting beyond current mobile-centric workflows.
Add broader automated API test coverage around uploads, ownership checks, and geospatial endpoints.
Refine upload retry telemetry and failure analytics to guide UX improvements in field conditions.
Contact
I can help manage the technical implementation across mobile UX, backend architecture, and scalable storage/upload patterns.