# formesean/sproutspot architecture

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

- Interactive diagram: https://gitdiagram.com/formesean/sproutspot
- Repository: https://github.com/formesean/sproutspot

## Overview

##### Project Type & Purpose
- This is a full-stack web application (Next.js + React) that provides an AI-powered digital-twin playground for farms. Users upload CSV data, view an actual farm grid, run “what-if” simulations, and receive AI-driven crop predictions and insights.

##### File-Structure Analysis
- **src/app/**: Next.js app directory (React pages, layouts, server/app-route APIs).
- **src/app/api/**: NextAuth and tRPC server routes under Next.js API (route.ts files).
- **src/server/**: Shared server code (tRPC router definitions, auth config, Prisma DB connection).
- **prisma/**: Schema for database models.
- **public/**: Static assets (videos, images).
- **components.json**, **src/components/**: Shared UI components (shadcn/ui, MagicUI).
- **start-database.sh**, **.env.example**: Local/dev database bootstrap.

##### README Insights
- **Frontend**: Next.js + TypeScript + Tailwind + shadcn/ui.
- **Backend**: NextAuth.js (auth), tRPC (typed RPC), Prisma ORM, Supabase (PostgreSQL)
- **AI/ML**: Gemini 2.0 Flash external service for predictions.
- **Workflows**: CSV upload → store in DB → duplicate for simulation → run ML inference → present in UI.

##### Main Components
a. **User & Browser**: The farmer’s web client.
b. **Next.js Frontend**:
- Pages & React components under `src/app` (Landing, Farm grid, Experimental playground, FAQ, etc.)
- Static assets in `/public`
- UI layer calling tRPC & REST endpoints.
c. **API Layer**:
- NextAuth.js (JWT/session management)
- tRPC router (`src/server/api/routers/*`) exposed via Next.js API routes (`src/app/api/trpc`)
d. **Business Logic / Services**:
- CSV parser & duplication logic (server-side code in TRPC resolvers)
- Simulation engine invoking ML models
- AI/ML service (external Gemini 2.0 Flash endpoint)
e. **Database**:
- Supabase/PostgreSQL accessed via Prisma client (`src/server/db.ts`)
- Tables: Users, Farms, GridItems, Playgrounds, Experiments, etc.
f. **External Services**:
- Supabase Auth (optional)
- Gemini 2.0 Flash for AI inference
- (Optional) Cloud storage for media (if used)

##### Relationships & Data Flow
- Browser → Next.js Frontend (HTTP/WS)
- Frontend → NextAuth endpoints (login/signup) → Issues session token
- Frontend → tRPC client → tRPC server/router → Business logic → Prisma → Database
- Business logic → calls out to Gemini AI API → receives predictions → writes back to DB or returns to client
- Frontend reads simulation results via tRPC and renders interactive grid/visualizations

##### Architectural Patterns & Principles
- **Layered Architecture**: UI → API layer → Business logic → Data layer
- **Server-Side Rendering** for initial pages (Next.js app directory) and **API routes** for dynamic calls
- **Typed contracts** end-to-end via tRPC
- **ORM Abstraction** via Prisma
- **Modular UI** with shadcn/ui and MagicUI components
- **Separation of Concerns**: authentication, data access, ML integration, UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["Farmer's Browser"]:::external

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Frontend["Next.js Frontend<br/>(src/app/)"]:::ui
        LandingPage["Landing Page<br/>(page.tsx)"]:::ui
        LayoutPage["Layout<br/>(layout.tsx)"]:::ui
        FarmGrid["Farm Grid & Playground<br/>(farm/page.tsx)"]:::ui
        FarmComponents["Farm Components<br/>(farm/_components/)"]:::ui
        FAQComp["FAQ & Shared UI<br/>(faq.tsx, nav-bar.tsx,<br/>footer.tsx, key-features.tsx)"]:::ui
        MagicUI["MagicUI Components<br/>(src/components/magicui/)"]:::ui
        ShadcnUI["shadcn/ui Components<br/>(src/components/ui/)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        NextAuthAPI["NextAuth.js API Route<br/>(src/app/api/auth/[...nextauth]/route.ts)"]:::api
        TRPCAPI["tRPC API Route<br/>(src/app/api/trpc/[trpc]/route.ts)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        TRPCConfig["tRPC Server Config<br/>(src/server/api/trpc.ts)"]:::biz
        RouterRoot["tRPC Root Router<br/>(src/server/api/root.ts)"]:::biz
        RouterPlayground["Playground Router<br/>(src/server/api/routers/playground.ts)"]:::biz
        AuthConfig["Auth Config<br/>(config.ts, index.ts)"]:::biz
        Utils["Utility Functions<br/>(src/lib/utils.ts)"]:::biz
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PrismaClient["Prisma Client<br/>(src/server/db.ts)"]:::data
        DB["Supabase/PostgreSQL"]:::data
        PrismaSchema["Prisma Schema<br/>(prisma/schema.prisma)"]:::data
        EnvConfig["Env Config<br/>(.env.example, src/env.js)"]:::data
        Types["Type Definitions<br/>(src/types/)"]:::data
        DBScript["DB Bootstrap Script<br/>(start-database.sh)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gemini["Gemini 2.0 Flash API"]:::ext
        SupabaseAuth["Supabase Auth"]:::ext
    end

    %% Connections
    User --> Frontend
    Frontend --> NextAuthAPI --> SupabaseAuth
    Frontend --> TRPCAPI
    Frontend --> MagicUI
    Frontend --> ShadcnUI
    TRPCAPI --> TRPCConfig --> RouterRoot --> RouterPlayground
    RouterPlayground --> Utils
    RouterPlayground --> AuthConfig --> SupabaseAuth
    RouterPlayground --> PrismaClient --> DB
    PrismaClient --> PrismaSchema
    PrismaClient --> EnvConfig
    PrismaClient --> DBScript
    PrismaClient --> Types
    RouterPlayground --> Gemini
    Gemini --> RouterPlayground

    %% Click Events
    click Frontend "https://github.com/formesean/sproutspot/tree/main/src/app/"
    click LandingPage "https://github.com/formesean/sproutspot/blob/main/src/app/page.tsx"
    click LayoutPage "https://github.com/formesean/sproutspot/blob/main/src/app/layout.tsx"
    click FarmGrid "https://github.com/formesean/sproutspot/blob/main/src/app/farm/page.tsx"
    click FarmComponents "https://github.com/formesean/sproutspot/tree/main/src/app/farm/_components/"
    click FAQComp "https://github.com/formesean/sproutspot/blob/main/src/app/_components/faq.tsx"
    click FAQComp "https://github.com/formesean/sproutspot/blob/main/src/app/_components/nav-bar.tsx"
    click FAQComp "https://github.com/formesean/sproutspot/blob/main/src/app/_components/footer.tsx"
    click FAQComp "https://github.com/formesean/sproutspot/blob/main/src/app/_components/key-features.tsx"
    click MagicUI "https://github.com/formesean/sproutspot/tree/main/src/components/magicui/"
    click ShadcnUI "https://github.com/formesean/sproutspot/tree/main/src/components/ui/"
    click NextAuthAPI "https://github.com/formesean/sproutspot/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click TRPCAPI "https://github.com/formesean/sproutspot/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click TRPCConfig "https://github.com/formesean/sproutspot/blob/main/src/server/api/trpc.ts"
    click RouterRoot "https://github.com/formesean/sproutspot/blob/main/src/server/api/root.ts"
    click RouterPlayground "https://github.com/formesean/sproutspot/blob/main/src/server/api/routers/playground.ts"
    click PrismaClient "https://github.com/formesean/sproutspot/blob/main/src/server/db.ts"
    click PrismaSchema "https://github.com/formesean/sproutspot/blob/main/prisma/schema.prisma"
    click AuthConfig "https://github.com/formesean/sproutspot/blob/main/src/server/auth/config.ts"
    click AuthConfig "https://github.com/formesean/sproutspot/blob/main/src/server/auth/index.ts"
    click Utils "https://github.com/formesean/sproutspot/blob/main/src/lib/utils.ts"
    click EnvConfig "https://github.com/formesean/sproutspot/blob/main/.env.example"
    click EnvConfig "https://github.com/formesean/sproutspot/blob/main/src/env.js"
    click DBScript "https://github.com/formesean/sproutspot/blob/main/start-database.sh"
    click Types "https://github.com/formesean/sproutspot/blob/main/src/types/crop.types.ts"
    click Types "https://github.com/formesean/sproutspot/blob/main/src/types/grid-item.types.ts"
    click Types "https://github.com/formesean/sproutspot/blob/main/src/types/playground.types.ts"

    %% Styles
    classDef ui fill:#D6E4FF,stroke:#1E3A8A;
    classDef api fill:#DCFCE7,stroke:#166534;
    classDef biz fill:#FEF3C7,stroke:#713F12;
    classDef data fill:#FFE7D9,stroke:#C2410C;
    classDef ext fill:#EDE9FE,stroke:#5B21B6;
    classDef external fill:#F3F4F6,stroke:#9CA3AF;
```
