# dolaposalim/fieldquad architecture

> Architecture diagram of the GitHub repository dolaposalim/fieldquad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dolaposalim/fieldquad
- Repository: https://github.com/dolaposalim/fieldquad

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    User["User"]:::user
    Browser["Browser UI"]:::browser

    User -->|"Interacts"| Browser

    %% Next.js Application
    subgraph "Next.js Application"
        direction TB
        subgraph "App Router"
            direction TB
            Layout["layout.tsx"]:::approuter
            Page["page.tsx"]:::approuter
            GlobalsCSS["globals.css"]:::approuter
        end
        subgraph "UI Layer"
            direction TB
            UIComponents["src/components/ui"]:::ui
        end
        subgraph "FieldQuAd Module"
            direction TB
            AnnotationCanvas["AnnotationCanvas.tsx"]:::feature
            AnnotationToolbar["AnnotationToolbar.tsx"]:::feature
            CropDialog["CropDialog.tsx"]:::feature
            ExportControls["ExportControls.tsx"]:::feature
            ImageUploader["ImageUploader.tsx"]:::feature
            Types["types.ts"]:::feature
        end
        subgraph "Hooks & Utils"
            direction TB
            MobileHook["use-mobile.tsx"]:::hooks
            ToastHook["use-toast.tsx"]:::hooks
            Utils["utils.ts"]:::utils
        end
        subgraph "AI Helpers"
            direction TB
            DevAI["dev.ts"]:::ai
            GenkitAI["genkit.ts"]:::ai
        end
        ExportEngine["Export Engine (TXT/JSON/XLSX)"]:::business
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Storage["Firebase Storage"]:::external
        Firestore["Firestore"]:::external
    end

    %% Build & Config
    subgraph "Build & Tooling Configuration"
        direction TB
        NextConfig["next.config.ts"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        PostCSS["postcss.config.mjs"]:::config
        TSConfig["tsconfig.json"]:::config
    end

    subgraph "Package Configuration"
        direction TB
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
    end

    %% Connections
    Browser -->|"Renders routes"| Layout
    Browser -->|"Renders routes"| Page
    Browser -->|"Uses styles"| GlobalsCSS
    Browser -->|"Renders UI components"| UIComponents

    Browser -->|"Annotation input"| AnnotationCanvas
    Browser -->|"Annotation controls"| AnnotationToolbar
    Browser -->|"Crop image"| CropDialog
    Browser -->|"Export controls"| ExportControls
    Browser -->|"Upload image UI"| ImageUploader

    Browser -->|"Hooks & events"| MobileHook
    Browser -->|"Notifications"| ToastHook
    Browser -->|"Utility functions"| Utils

    Browser -->|"Optional AI suggestions"| DevAI
    Browser -->|"Optional AI suggestions"| GenkitAI

    Browser -->|"Trigger exports"| ExportEngine
    ExportEngine -->|"Downloads to user"| User

    Browser -->|"Upload image"| Storage
    Browser -->|"Save annotations"| Firestore

    %% Click Events
    click Layout "https://github.com/dolaposalim/fieldquad/blob/master/src/app/layout.tsx"
    click Page "https://github.com/dolaposalim/fieldquad/blob/master/src/app/page.tsx"
    click GlobalsCSS "https://github.com/dolaposalim/fieldquad/blob/master/src/app/globals.css"
    click AnnotationCanvas "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/AnnotationCanvas.tsx"
    click AnnotationToolbar "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/AnnotationToolbar.tsx"
    click CropDialog "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/CropDialog.tsx"
    click ExportControls "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/ExportControls.tsx"
    click ImageUploader "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/ImageUploader.tsx"
    click Types "https://github.com/dolaposalim/fieldquad/blob/master/src/components/fieldquad/types.ts"
    click UIComponents "https://github.com/dolaposalim/fieldquad/tree/master/src/components/ui"
    click MobileHook "https://github.com/dolaposalim/fieldquad/blob/master/src/hooks/use-mobile.tsx"
    click ToastHook "https://github.com/dolaposalim/fieldquad/blob/master/src/hooks/use-toast.tsx"
    click Utils "https://github.com/dolaposalim/fieldquad/blob/master/src/lib/utils.ts"
    click DevAI "https://github.com/dolaposalim/fieldquad/blob/master/src/ai/dev.ts"
    click GenkitAI "https://github.com/dolaposalim/fieldquad/blob/master/src/ai/genkit.ts"
    click NextConfig "https://github.com/dolaposalim/fieldquad/blob/master/next.config.ts"
    click TailwindConfig "https://github.com/dolaposalim/fieldquad/blob/master/tailwind.config.ts"
    click PostCSS "https://github.com/dolaposalim/fieldquad/blob/master/postcss.config.mjs"
    click TSConfig "https://github.com/dolaposalim/fieldquad/blob/master/tsconfig.json"
    click PackageJSON "https://github.com/dolaposalim/fieldquad/blob/master/package.json"
    click PackageLock "https://github.com/dolaposalim/fieldquad/blob/master/package-lock.json"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef browser fill:#bbf,stroke:#333,stroke-width:1px
    classDef approuter fill:#def,stroke:#333,stroke-width:1px
    classDef ui fill:#9cf,stroke:#333,stroke-width:1px
    classDef feature fill:#8f8,stroke:#333,stroke-width:1px
    classDef hooks fill:#afc,stroke:#333,stroke-width:1px
    classDef utils fill:#cfc,stroke:#333,stroke-width:1px
    classDef ai fill:#afa,stroke:#333,stroke-width:1px
    classDef business fill:#dfd,stroke:#333,stroke-width:1px
    classDef external fill:#fdc,stroke:#333,stroke-width:1px
    classDef config fill:#eee,stroke:#333,stroke-width:1px
```
