How dolaposalim/fieldquad works
Project Type and Purpose
• Project Type: Full-stack (client-heavy) web application
• Framework: Next.js (React)
• Purpose: Provide researchers/field ecologists with a browser-based UI to upload photoquadrants, annotate species coverage, extract coordinates, compute percentage coverage, and export results (TXT, JSON, XLSX).
• External Services: Google Firebase (Storage for images, Firestore for data) and optional AI helper modules under src/ai.
File Structure
Top-level:
• next.config.ts, tailwind.config.ts, postcss.config.mjs – build/tooling
• package.json, tsconfig.json – dependencies and TypeScript config
src/
• src/app/… – Next.js 13+ App Router (globals.css, layout.tsx, page.tsx)
• src/components/fieldquad/… – Core annotation feature set (canvas, toolbar, crop dialog, export controls, uploader)
• src/components/ui/… – Reusable atomic UI (buttons, modals, inputs, sidebar, etc.)
• src/hooks/… – Custom React hooks (mobile detection, toast notifications)
• src/lib/utils.ts – Shared utility functions
• src/ai/… – AI-related helpers (possibly for automated suggestions or genkit integration)
Extract Additional Insights from README
• Coordinate Extraction: raw and normalized
• Percentage Coverage: computed client-side
• Export Formats: TXT, JSON, XLSX
• Hosting/Deployment: can be hosted on Vercel or Firebase Hosting
Main Components
a. Client Browser (User)
b. Next.js Frontend
– App Router (pages under src/app)
– UI Layer (src/components/ui)
– FieldQuAd Module (src/components/fieldquad)
– Hooks & Utils (src/hooks, src/lib)
– AI Helpers (src/ai)
c. External Services
– Firebase Storage (Image upload)
– Firestore (Optional: saving annotation metadata)
d. Export Engine (client-side library generating TXT/JSON/XLSX files)
Relationships & Data Flows
• User → Browser UI
• Browser UI
→ FieldQuAd Canvas (Annotation input)
→ Hooks & Utils for event handling
→ AI Helpers (optional)
→ Export Engine
• When “Upload Image” is triggered → Next.js API Route or direct Firebase SDK call → Firebase Storage
• On “Save Annotations” (if using Firestore) → Next.js API Route or Firebase SDK call → Firestore
• Exports remain in browser memory, then download to user
Architectural Patterns & Design Principles
• Component-based UI (Atomic Design)
• Separation of Concerns:
– Presentation Layer (ui components)
– Feature Layer (fieldquad)
– Cross-cutting (hooks, utils)
• Next.js App Router for route-based lazy loading
• Serverless/external services (Firebase) vs. purely client-side for most logic
• Tailwind CSS for styling