---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- domain/security
- status/active
- tech/azure-ad
- tech/gemini
- tech/react
- tech/typescript
type: sop
---

# SmartCrop26 Developer Manual

## Architecture Overview
SmartCrop26 is a client-side React application built with Vite. It utilizes shadcn-ui for component styling and Tailwind CSS for layout. The core functionality involves image processing, which can be performed locally via browser-based edge detection or remotely via Google's Gemini AI API.

## Tech Stack
- **Frontend Framework**: React 18+
- **Build Tool**: Vite
- **Language**: TypeScript
- **Styling**: Tailwind CSS, shadcn-ui
- **State Management**: React Context (for Toasts), standard React Hooks
- **Testing**: Vitest, jsdom
- **AI Integration**: Google Gemini API (via REST)

## Local Setup

1. **Clone the Repository**:
   ```bash
   git clone <YOUR_GIT_URL>
   cd smartcrop26
   ```

2. **Install Dependencies**:
   ```bash
   npm install
   ```

3. **Environment Configuration**:
   Copy `.env.example` to `.env` and fill in the required credentials:
   ```bash
   cp .env.example .env
   ```
   You must provide a valid `VITE_GOOGLE_API_KEY` for AI-powered analysis.

4. **Run Development Server**:
   ```bash
   npm run dev
   ```
   The app will run at `http://localhost:8080`.

## Environment Variables
| Variable | Required | Description |
| :--- | :--- | :--- |
| `VITE_GOOGLE_API_KEY` | Yes (for AI mode) | Google Gemini API Key |
| `VITE_AZURE_TENANT_ID` | No | Azure AD Tenant ID (if SSO is enabled) |
| `VITE_AZURE_CLIENT_ID` | No | Azure AD Client ID |
| `VITE_AZURE_REDIRECT_URI` | No | Azure AD Redirect URI |

## Key Services & Entry Points

### Image Analysis Logic
Located in `src/lib/`:
- **`analyze-image.ts`**: Calls Google Gemini API for high-accuracy AI cropping suggestions.
- **`analyze-local.ts`**: Implements a fallback client-side algorithm using Canvas and Sobel edge detection. This is useful for offline or privacy-sensitive scenarios where API keys are unavailable.

### State Management
- **`src/hooks/use-toast.ts`**: Custom toast notification system using a reducer pattern for managing UI feedback.

### Configuration
- **`vite.config.ts`**: Defines the build path (`/smartcrop26/` in production) and aliases (`@` points to `./src`).
- **`tailwind.config.ts`**: Custom theme extensions including font families (Montserrat) and animation keyframes.

## API Reference

### Google Gemini Endpoint
- **URL**: `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent`
- **Method**: POST
- **Headers**: `Content-Type: application/json`
- **Body**: JSON object containing `systemInstruction` and `contents` (image data as base64).

## Deployment

### Via Lovable
1. Open the project in Lovable.
2. Navigate to **Share** -> **Publish**.

### Manual Deployment
1. Run `npm run build` to generate the static files in the `dist` folder.
2. Upload the contents of `dist` to your static hosting provider (e.g., Netlify, Vercel, GitHub Pages).
3. Ensure your hosting provider is configured to support SPA routing (redirect all routes to `index.html`).

## Known Gotchas
- **API Key Security**: Ensure `VITE_GOOGLE_API_KEY` is not exposed in public repositories. Use `.env` files and gitignore.
- **CORS**: When testing locally with AI features, ensure your Google API Key has the appropriate HTTP referrer restrictions or IP restrictions if deploying.
- **Performance**: The local `analyze-local.ts` function runs in the main thread. For very large images, consider using Web Workers to prevent UI freezing, though the current implementation scales down images to 400px max dimension for performance.
- **Path Alias**: The `@` alias is configured in both `vite.config.ts` and `vitest.config.ts`. Ensure both are synced if adding new modules.