Consolidate repositories: Remove nested frontend .git and merge into main repository

- Remove nested git repository from bugulma/frontend/.git
- Add all frontend files to main repository tracking
- Convert from separate frontend/backend repos to unified monorepo
- Preserve all frontend code and development history as tracked files
- Eliminate nested repository complexity for simpler development workflow

This creates a proper monorepo structure with frontend and backend
coexisting in the same repository for easier development and deployment.

bugulma/frontend

@@ -1 +0,0 @@
-Subproject commit 9f43a19ef2a2a435b9f94dc04f92de02b7b160ae

bugulma/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

bugulma/frontend/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "tabWidth": 2,
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "bracketSameLine": false
+}

bugulma/frontend/.yarnrc.yml

@@ -0,0 +1,9 @@
+# Yarn configuration for standalone project
+# This directory is a standalone project, not part of parent workspace
+
+# Use node_modules linker (standard approach for standalone projects)
+nodeLinker: node-modules
+
+# Enable global cache for better performance
+enableGlobalCache: true
+

bugulma/frontend/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Frontend Architecture
+
+## User-Friendly Abstraction Layer
+
+The frontend uses **business-friendly terminology** that is intuitive for users, while the backend uses **technical terminology** optimized for the matching engine.
+
+### UI Layer (User-Friendly)
+
+- **Needs**: What the organization requires (e.g., "Heat", "Water", "Materials")
+- **Offers**: What the organization provides (e.g., "Waste heat", "Steam", "By-products")
+- Simple, clear language that business users understand
+
+### Backend Layer (Technical)
+
+- **ResourceFlow**: Technical entity with `direction` ('input' or 'output')
+- **ResourceType**: Enum values ('heat', 'water', 'steam', 'CO2', etc.)
+- Optimized for matching algorithms and data processing
+
+### Translation Layer
+
+The `lib/resource-flow-mapper.ts` converts between these layers:
+
+```typescript
+// User enters: "I need 100 kg of materials"
+// Frontend stores: { resource_name: "materials", quantity: "100 kg", direction: "need" }
+// Mapper converts to: { direction: "input", type: "materials", quantity: { amount: 100, unit: "kg" } }
+```
+
+## Benefits
+
+1. **Better UX**: Users don't need to understand technical concepts like "ResourceFlow" or "input/output"
+2. **Clean Separation**: Frontend focuses on user experience, backend focuses on technical implementation
+3. **Maintainability**: Changes to backend structure don't require UI changes
+4. **Flexibility**: Can improve mapping logic without changing user interface
+
+## Data Flow
+
+```
+User Input (Needs/Offers)
+    ↓
+Form Schema (Zod validation)
+    ↓
+Organization Form Data
+    ↓
+Resource Flow Mapper (conversion layer)
+    ↓
+Backend API (ResourceFlow with direction)
+    ↓
+Backend Storage & Matching Engine
+```
+
+## Type Safety
+
+- **Frontend Types**: User-friendly (`needs`, `offers` with `resource_name`)
+- **Backend Types**: Technical (`ResourceFlow` with `Direction`, `Type`)
+- **Zod Schemas**: Validate at both layers
+- **Runtime Validation**: All API responses validated with Zod

bugulma/frontend/ASYNC_RENDERING_GUIDE.md

@@ -0,0 +1,236 @@
+# Async Rendering Guide
+
+## Overview
+
+All pages and components are designed to render **asynchronously** - they never block on API requests. Components render immediately with loading states or placeholder data, and data updates asynchronously as it arrives from the backend.
+
+## Key Principles
+
+### 1. **Non-Blocking Rendering**
+
+- Components render immediately, even before API data arrives
+- Use `placeholderData` in React Query hooks to provide safe defaults
+- Never wait for API responses before rendering
+
+### 2. **Progressive Data Loading**
+
+- Initial render shows loading states or empty states
+- Data updates asynchronously as API responses arrive
+- Multiple API calls happen in parallel, not sequentially
+
+### 3. **Safe Defaults**
+
+- All hooks return safe default structures (empty arrays, undefined, etc.)
+- Components handle `undefined` and `null` gracefully
+- No assumptions about data structure
+
+## Implementation Patterns
+
+### React Query Hooks with placeholderData
+
+All `useQuery` hooks include `placeholderData` to prevent blocking:
+
+```typescript
+// ✅ Good - Renders immediately with empty array
+export function useOrganizations() {
+  return useQuery({
+    queryKey: organizationKeys.lists(),
+    queryFn: getOrganizations,
+    placeholderData: [], // Component renders immediately
+    staleTime: 30 * 1000,
+  });
+}
+
+// ✅ Good - Renders immediately with undefined
+export function useOrganization(id: string | null | undefined) {
+  return useQuery({
+    queryKey: organizationKeys.detail(id!),
+    queryFn: () => getOrganizationById(id!),
+    enabled: !!id,
+    placeholderData: undefined, // Component handles undefined
+  });
+}
+```
+
+### Component Pattern
+
+Components should handle placeholder data gracefully:
+
+```typescript
+// ✅ Good - Handles placeholder data
+const MyComponent = () => {
+  const { data, isLoading } = useOrganizations();
+
+  // placeholderData ensures data is always an array
+  const organizations = Array.isArray(data) ? data : [];
+
+  // Render immediately, show loading only if no placeholder data
+  if (isLoading && organizations.length === 0) {
+    return <LoadingSpinner />;
+  }
+
+  return <div>{/* Render with data */}</div>;
+};
+```
+
+### Safe Array Operations
+
+Always check arrays before operations:
+
+```typescript
+// ✅ Good - Safe array operations
+const items = Array.isArray(data?.items) ? data.items : [];
+const filtered = items.filter(item => item?.id);
+const mapped = items.map(item => ({ ...item }));
+
+// ❌ Bad - Assumes data is always an array
+const items = data.items; // Could be undefined
+items.filter(...); // Crashes if undefined
+```
+
+## Hooks Updated
+
+All API hooks now include `placeholderData`:
+
+### Organizations
+
+- `useOrganizations()` - `placeholderData: []`
+- `useOrganization(id)` - `placeholderData: undefined`
+- `useUserOrganizations()` - `placeholderData: []`
+
+### Sites
+
+- `useSite(id)` - `placeholderData: undefined`
+- `useSitesByOrganization(id)` - `placeholderData: []`
+- `useNearbySites(query)` - `placeholderData: []`
+
+### Resource Flows
+
+- `useResourceFlow(id)` - `placeholderData: undefined`
+- `useResourceFlowsBySite(id)` - `placeholderData: []`
+- `useResourceFlowsByOrganization(id)` - `placeholderData: []`
+
+### Proposals
+
+- `useProposals()` - `placeholderData: { proposals: [] }`
+- `useProposal(id)` - `placeholderData: undefined`
+- `useProposalsForOrganization(id)` - `placeholderData: { incoming: [], outgoing: [] }`
+
+### Matching
+
+- `useDirectSymbiosis(id)` - `placeholderData: { providers: [], consumers: [] }`
+- `useFindMatches(id)` - `placeholderData: { matches: [] }`
+
+### Analytics
+
+- `useConnectionStatistics()` - `placeholderData: { total_connections: 0 }`
+- `useSupplyDemandAnalysis()` - `placeholderData: { supply: [], demand: [] }`
+- `useDashboardStatistics()` - `placeholderData: { total_organizations: 0, recent_activity: [] }`
+
+## Benefits
+
+1. **Instant Rendering**: Pages render immediately, no waiting for APIs
+2. **Better UX**: Users see loading states or empty states right away
+3. **No Freezing**: Components never block on API requests
+4. **Progressive Enhancement**: Data appears as it loads
+5. **Error Resilience**: Safe defaults prevent crashes
+
+## Testing
+
+To verify async rendering:
+
+1. **Network Throttling**: Use DevTools to throttle network to "Slow 3G"
+2. **Check Rendering**: Page should render immediately with loading states
+3. **Verify Updates**: Data should appear as API responses arrive
+4. **Test Empty States**: Disable network to see empty state handling
+
+## Common Patterns
+
+### Pattern 1: List with Loading State
+
+```typescript
+const { data, isLoading } = useOrganizations();
+const items = Array.isArray(data) ? data : [];
+
+if (isLoading && items.length === 0) {
+  return <LoadingSpinner />;
+}
+
+return <List items={items} />;
+```
+
+### Pattern 2: Detail with Placeholder
+
+```typescript
+const { data, isLoading } = useOrganization(id);
+
+if (isLoading && !data) {
+  return <Skeleton />;
+}
+
+if (!data) {
+  return <NotFound />;
+}
+
+return <Detail data={data} />;
+```
+
+### Pattern 3: Parallel Loading
+
+```typescript
+// Multiple queries load in parallel
+const { data: org } = useOrganization(id);
+const { data: sites } = useSitesByOrganization(id);
+const { data: flows } = useResourceFlowsByOrganization(id);
+
+// All render immediately with placeholderData
+// Updates happen asynchronously as data arrives
+```
+
+## Anti-Patterns to Avoid
+
+### ❌ Blocking on Data
+
+```typescript
+// Bad - Blocks render until data arrives
+const { data } = useOrganizations();
+if (!data) return null; // Blocks render
+```
+
+### ❌ Unsafe Array Operations
+
+```typescript
+// Bad - Crashes if data is undefined
+const items = data.items;
+items.map(...); // Error if items is undefined
+```
+
+### ❌ Synchronous Operations in Render
+
+```typescript
+// Bad - Blocks render
+const processed = heavyComputation(data); // Blocks
+```
+
+## Performance Considerations
+
+1. **placeholderData** is lightweight - just empty arrays/objects
+2. **React Query** handles caching and deduplication
+3. **Components** re-render only when data actually changes
+4. **Memoization** prevents unnecessary recalculations
+
+## Migration Checklist
+
+- [x] All `useQuery` hooks have `placeholderData`
+- [x] Components handle `undefined` and `null` safely
+- [x] Array operations are guarded with `Array.isArray()`
+- [x] Loading states show only when no placeholder data exists
+- [x] Error states don't block rendering
+- [x] Context providers don't block on data
+
+## Future Improvements
+
+1. **Suspense Boundaries**: Consider React Suspense for better loading UX
+2. **Optimistic Updates**: Update UI immediately, rollback on error
+3. **Streaming**: For large datasets, consider streaming responses
+4. **Prefetching**: Prefetch data before navigation

bugulma/frontend/App.tsx

@@ -0,0 +1,15 @@
+import React, { useEffect } from 'react';
+import { initializeSecurity } from '@/lib/security';
+import { AppProvider } from '@/providers/AppProvider';
+import AppRouter from '@/src/AppRouter';
+
+const App = ({ children }: { children?: React.ReactNode }) => {
+  // Initialize security measures on app startup
+  useEffect(() => {
+    initializeSecurity();
+  }, []);
+
+  return <AppProvider>{children || <AppRouter />}</AppProvider>;
+};
+
+export default App;

bugulma/frontend/BACKEND_AI_ENDPOINTS.md

@@ -0,0 +1,250 @@
+# Backend AI Endpoints Specification
+
+This document specifies the AI/LLM endpoints that the frontend expects from the backend. The frontend is now "dumb" and just calls these endpoints.
+
+## Endpoints
+
+All endpoints require authentication (Bearer token) except where noted.
+
+### Base Path
+
+All AI endpoints are under `/api/ai/`
+
+### 1. Extract Data from Text
+
+**POST** `/api/ai/extract/text`
+
+Extract structured organization data from text.
+
+**Request:**
+
+```json
+{
+  "text": "Company name: Acme Corp, Sector: Manufacturing, Description: ..."
+}
+```
+
+**Response:**
+
+```json
+{
+  "name": "Acme Corp",
+  "sector": "manufacturing",
+  "description": "...",
+  "website": "https://acme.com",
+  ...
+}
+```
+
+### 2. Extract Data from File
+
+**POST** `/api/ai/extract/file`
+
+Extract structured organization data from an image file.
+
+**Request:**
+
+- Content-Type: `multipart/form-data`
+- Body: `file` (File/Blob)
+
+**Response:**
+
+```json
+{
+  "name": "Acme Corp",
+  "sector": "manufacturing",
+  "description": "...",
+  ...
+}
+```
+
+### 3. Analyze Symbiosis
+
+**POST** `/api/ai/analyze/symbiosis`
+
+Analyze potential symbiotic relationships for an organization.
+
+**Request:**
+
+```json
+{
+  "organization_id": "org-123"
+}
+```
+
+**Response:**
+
+```json
+{
+  "matches": [
+    {
+      "partner_id": "org-456",
+      "partner_name": "Partner Corp",
+      "reason": "Can provide waste heat for your processes",
+      "score": 0.85
+    }
+  ]
+}
+```
+
+### 4. Get Web Intelligence
+
+**POST** `/api/ai/web-intelligence`
+
+Get web intelligence about an organization.
+
+**Request:**
+
+```json
+{
+  "organization_name": "Acme Corp"
+}
+```
+
+**Response:**
+
+```json
+{
+  "text": "Acme Corp is a leading manufacturer...",
+  "sources": [
+    {
+      "uri": "https://example.com/article",
+      "title": "Article Title"
+    }
+  ]
+}
+```
+
+### 5. Get Search Suggestions
+
+**POST** `/api/ai/search-suggestions`
+
+Get search suggestions based on query.
+
+**Request:**
+
+```json
+{
+  "query": "manufacturing"
+}
+```
+
+**Response:**
+
+```json
+["manufacturing companies", "manufacturing sector", "industrial manufacturing"]
+```
+
+### 6. Generate Organization Description
+
+**POST** `/api/ai/generate/description`
+
+Generate a professional organization description.
+
+**Request:**
+
+```json
+{
+  "name": "Acme Corp",
+  "sector_key": "manufacturing",
+  "keywords": "sustainable, green energy, innovation"
+}
+```
+
+**Response:**
+
+```json
+{
+  "description": "Acme Corp is a forward-thinking manufacturing company..."
+}
+```
+
+### 7. Generate Historical Context
+
+**POST** `/api/ai/generate/historical-context`
+
+Generate historical context for a landmark.
+
+**Request:**
+
+```json
+{
+  "landmark": {
+    "id": "landmark-1",
+    "name": "Old Factory",
+    "period": "1920s",
+    "originalPurpose": "Textile manufacturing",
+    "currentStatus": "Converted to offices"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "context": "The Old Factory stands as a testament to..."
+}
+```
+
+### 8. Chat / Send Message
+
+**POST** `/api/ai/chat`
+
+Send a simple message to the AI.
+
+**Request:**
+
+```json
+{
+  "message": "What is industrial symbiosis?",
+  "system_instruction": "You are a helpful assistant about industrial symbiosis."
+}
+```
+
+**Response:**
+
+```json
+{
+  "response": "Industrial symbiosis is..."
+}
+```
+
+## Error Handling
+
+All endpoints should return standard error responses:
+
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE"
+}
+```
+
+Status codes:
+
+- `400` - Bad Request
+- `401` - Unauthorized
+- `500` - Internal Server Error
+
+## Implementation Notes
+
+1. **Authentication**: All endpoints (except possibly chat) require JWT authentication
+2. **File Uploads**: Use `multipart/form-data` for file uploads
+3. **Rate Limiting**: Consider implementing rate limiting for AI endpoints
+4. **Caching**: Consider caching responses where appropriate
+5. **Cost Management**: Track and limit AI API usage
+
+## Frontend Usage
+
+The frontend uses these endpoints via `services/ai-api.ts`:
+
+```typescript
+import * as aiApi from './services/ai-api';
+
+// Extract data from text
+const data = await aiApi.extractDataFromText({ text: '...' });
+
+// Analyze symbiosis
+const matches = await aiApi.analyzeSymbiosis({ organization_id: 'org-123' });
+```

bugulma/frontend/BACKEND_ALIGNMENT.md

@@ -0,0 +1,180 @@
+# Frontend-Backend Alignment
+
+This document describes the alignment between the frontend and the enhanced Go backend.
+
+## Architecture Overview
+
+The frontend now communicates with the backend through:
+
+1. **API Client Layer** (`lib/api-client.ts`): Base HTTP client with authentication
+2. **Service Layer** (`services/*-api.ts`): Type-safe API service functions
+3. **React Hooks** (`hooks/api/*.ts`): React Query hooks for data fetching and mutations
+4. **Backend Schemas** (`schemas/backend/*.ts`): Zod schemas matching backend domain models
+
+## API Endpoints
+
+### Authentication
+
+- `POST /auth/login` - JWT authentication
+
+### Organizations
+
+- `GET /api/organizations` - List all organizations
+- `GET /api/organizations/:id` - Get organization by ID
+- `POST /api/organizations` - Create organization
+- `DELETE /api/organizations/:id` - Delete organization
+
+### Sites
+
+- `POST /api/sites` - Create site
+- `GET /api/sites/:id` - Get site by ID
+- `GET /api/sites/business/:businessId` - Get sites by business
+- `GET /api/sites/nearby?lat=&lng=&radius=` - Find sites within radius
+- `DELETE /api/sites/:id` - Delete site
+
+### Resource Flows
+
+- `POST /api/resources` - Create resource flow
+- `GET /api/resources/:id` - Get resource flow by ID
+- `GET /api/resources/site/:siteId` - Get flows by site
+- `GET /api/resources/business/:businessId` - Get flows by business
+- `DELETE /api/resources/:id` - Delete resource flow
+
+### Matching Engine
+
+- `GET /api/matching/resource/:resourceId?max_distance_km=50&min_score=0.3&limit=20` - Find matches for a resource
+
+## Data Models
+
+### Organization
+
+- Simplified compared to frontend's previous model
+- No embedded needs/offers (these are now separate ResourceFlow entities)
+- Fields: `ID`, `Name`, `Sector`, `Description`, `LogoURL`, `Website`, `Address`, `Verified`, `CreatedAt`, `UpdatedAt`
+
+### Site
+
+- Represents a physical location
+- Fields: `ID`, `Name`, `Address`, `Latitude`, `Longitude`, `SiteType`, `FloorAreaM2`, `OwnerBusinessID`, `CreatedAt`, `UpdatedAt`
+
+### ResourceFlow
+
+- Represents input/output resource flows
+- Direction: `input` or `output`
+- Types: `heat`, `water`, `steam`, `CO2`, `biowaste`, `cooling`, `logistics`, `materials`, `service`
+- Includes: `Quality`, `Quantity`, `TimeProfile`, `EconomicData`, `Constraints`, `ServiceDetails`
+- Precision levels: `rough`, `estimated`, `measured`
+- Source types: `declared`, `device`, `calculated`
+
+### Match
+
+- Represents a match between two resource flows
+- Status: `suggested`, `negotiating`, `reserved`, `contracted`, `live`, `failed`, `cancelled`
+- Includes: `CompatibilityScore`, `EconomicValue`, `DistanceKm`, `RiskAssessment`, `EconomicImpact`, `TransportationEstimate`
+
+## Usage Examples
+
+### Using Organizations API
+
+```typescript
+import { useOrganizations, useCreateOrganization } from '@/hooks/api';
+
+function OrganizationsList() {
+  const { data: organizations, isLoading } = useOrganizations();
+  const createOrg = useCreateOrganization();
+
+  const handleCreate = async () => {
+    await createOrg.mutateAsync({
+      name: 'New Organization',
+      sector: '35.30',
+      description: 'Description',
+    });
+  };
+
+  // ...
+}
+```
+
+### Using Resource Flows API
+
+```typescript
+import { useResourceFlowsByBusiness, useCreateResourceFlow } from '@/hooks/api';
+
+function ResourceFlowsList({ businessId }: { businessId: string }) {
+  const { data: flows } = useResourceFlowsByBusiness(businessId);
+  const createFlow = useCreateResourceFlow();
+
+  const handleCreate = async () => {
+    await createFlow.mutateAsync({
+      business_id: businessId,
+      site_id: 'site-id',
+      direction: 'output',
+      type: 'heat',
+      quantity: {
+        amount: 500,
+        unit: 'kWh',
+        temporal_unit: 'per_hour',
+      },
+      quality: {
+        temperature_celsius: 65.0,
+        physical_state: 'liquid',
+      },
+    });
+  };
+
+  // ...
+}
+```
+
+### Using Matching API
+
+```typescript
+import { useFindMatches } from '@/hooks/api';
+
+function MatchesList({ resourceId }: { resourceId: string }) {
+  const { data: matchesData } = useFindMatches(resourceId, {
+    max_distance_km: 30,
+    min_score: 0.3,
+    limit: 10,
+  });
+
+  // matchesData.matches contains the array of matches
+  // matchesData.count contains the count
+}
+```
+
+## Authentication
+
+The `AuthContext` has been updated to:
+
+- Use the API client's `login` function
+- Decode JWT tokens to extract user information
+- Store tokens in localStorage
+- Automatically include Bearer tokens in API requests
+
+## Migration Notes
+
+### Breaking Changes
+
+1. **Organization Model**: The frontend's previous organization model included embedded `needs` and `offers`. These are now separate `ResourceFlow` entities that must be created independently.
+
+2. **Field Naming**: Backend uses Go's default JSON encoding (capitalized field names) for main structs, but snake_case for nested structs. The schemas reflect this.
+
+3. **Data Structure**: Organizations no longer contain resource flows directly. Use `useResourceFlowsByBusiness(businessId)` to fetch related resource flows.
+
+### Next Steps
+
+1. Update components that display organizations to use the new API hooks
+2. Create components for managing resource flows separately
+3. Implement match visualization and management UI
+4. Add error handling and loading states throughout
+5. Consider adding optimistic updates for better UX
+
+## Field Name Convention
+
+**Note**: The backend Go structs use capitalized field names (Go's default JSON encoding) for main entities, but nested structs use snake_case JSON tags. The frontend schemas match this convention:
+
+- Main struct fields: `ID`, `Name`, `Sector`, etc. (capitalized)
+- Nested struct fields: `temperature_celsius`, `cost_in`, etc. (snake_case)
+
+If the actual API responses differ, adjust the schemas accordingly.

bugulma/frontend/BACKEND_ALIGNMENT_STATUS.md

@@ -0,0 +1,92 @@
+# Backend Alignment Status
+
+## Current State
+
+The frontend is **fully aligned** with the organization-based architecture. All schemas and API calls use `organization` terminology. The backend database will be updated directly, so no legacy field support is needed.
+
+## Frontend Alignment
+
+### ✅ Schemas (Clean - No Legacy Fields)
+
+**Site Schema** (`schemas/backend/site.ts`):
+
+- Request field: `owner_organization_id` ✅
+- Response field: `OwnerOrganizationID` ✅
+- **No legacy fields - clean schema**
+
+**Resource Flow Schema** (`schemas/backend/resource-flow.ts`):
+
+- Request field: `organization_id` ✅
+- Response field: `OrganizationID` ✅
+- **No legacy fields - clean schema**
+
+### ✅ API Endpoints (Clean - No Fallbacks)
+
+**Sites API** (`services/sites-api.ts`):
+
+- Endpoint: `/api/sites/organization/:organizationId` ✅
+- **No fallback - expects backend to be updated**
+
+**Resources API** (`services/resources-api.ts`):
+
+- Endpoint: `/api/resources/organization/:organizationId` ✅
+- **No fallback - expects backend to be updated**
+
+### ✅ Request Payloads
+
+**Create Site** (`components/add-organization/AddOrganizationWizard.tsx`):
+
+- Uses: `owner_organization_id` ✅
+- **Ready for backend refactoring**
+
+**Create Resource Flow** (`lib/resource-flow-mapper.ts`):
+
+- Uses: `organization_id` ✅
+- **Ready for backend refactoring**
+
+## Backend Refactoring Checklist
+
+When backend is updated, verify:
+
+### API Endpoints
+
+- [ ] `/api/sites/organization/:organizationId` exists
+- [ ] `/api/resources/organization/:organizationId` exists
+- [ ] Old `/business/` endpoints can be removed (or kept for backward compatibility)
+
+### Request Fields
+
+- [ ] `owner_organization_id` accepted in site creation
+- [ ] `organization_id` accepted in resource flow creation
+
+### Response Fields
+
+- [ ] Sites return `OwnerOrganizationID` (not `OwnerBusinessID`)
+- [ ] Resource flows return `OrganizationID` (not `BusinessID`)
+
+## Backend Requirements
+
+For the frontend to work correctly, the backend must:
+
+1. **Database Migration**: Update database columns:
+   - `sites.owner_business_id` → `sites.owner_organization_id`
+   - `resource_flows.business_id` → `resource_flows.organization_id`
+
+2. **API Endpoints**: Implement new endpoints:
+   - `/api/sites/organization/:organizationId`
+   - `/api/resources/organization/:organizationId`
+
+3. **Request Fields**: Accept new field names:
+   - `owner_organization_id` in site creation
+   - `organization_id` in resource flow creation
+
+4. **Response Fields**: Return new field names:
+   - `OwnerOrganizationID` in site responses
+   - `OrganizationID` in resource flow responses
+
+## Notes
+
+- Frontend schemas use only `organization` terminology (no legacy support)
+- All frontend code expects the new field names
+- No fallback logic - backend must be updated for frontend to work
+- Database migration can be done directly (as mentioned by user)

bugulma/frontend/BACKEND_ENDPOINTS_NEEDED.md

@@ -0,0 +1,310 @@
+# Backend Endpoints Needed
+
+This document lists all backend endpoints that need to be implemented to complete the frontend-to-backend migration.
+
+## AI/LLM Endpoints
+
+Already documented in `BACKEND_AI_ENDPOINTS.md`:
+
+- ✅ `POST /api/ai/extract/text`
+- ✅ `POST /api/ai/extract/file`
+- ✅ `POST /api/ai/analyze/symbiosis`
+- ✅ `POST /api/ai/web-intelligence`
+- ✅ `POST /api/ai/search-suggestions`
+- ✅ `POST /api/ai/generate/description`
+- ✅ `POST /api/ai/generate/historical-context`
+- ✅ `POST /api/ai/chat`
+
+**Additional needed:**
+
+- `POST /api/ai/chat/stream` - Streaming chat (SSE or WebSocket)
+
+---
+
+## Proposal Endpoints
+
+### List Proposals
+
+**GET** `/api/proposals`
+
+**Query Parameters:**
+
+- `organization_id` (optional) - Filter by organization
+- `status` (optional) - Filter by status (pending, accepted, rejected)
+- `type` (optional) - Filter by type (incoming, outgoing)
+
+**Response:**
+
+```json
+{
+  "proposals": [
+    {
+      "id": "prop-1",
+      "from_org_id": "org-1",
+      "to_org_id": "org-2",
+      "resource_id": "resource-1",
+      "resource_type": "input",
+      "resource_name": "Waste Heat",
+      "message": "Proposal message...",
+      "status": "pending",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "count": 1
+}
+```
+
+### Get Proposal
+
+**GET** `/api/proposals/:id`
+
+**Response:**
+
+```json
+{
+  "id": "prop-1",
+  "from_org_id": "org-1",
+  "to_org_id": "org-2",
+  "resource_id": "resource-1",
+  "resource_type": "input",
+  "resource_name": "Waste Heat",
+  "message": "Proposal message...",
+  "status": "pending",
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### Create Proposal
+
+**POST** `/api/proposals`
+
+**Request:**
+
+```json
+{
+  "from_org_id": "org-1",
+  "to_org_id": "org-2",
+  "resource_id": "resource-1",
+  "resource_type": "input",
+  "resource_name": "Waste Heat",
+  "message": "Proposal message..."
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "prop-1",
+  "status": "pending",
+  "created_at": "2024-01-01T00:00:00Z",
+  ...
+}
+```
+
+### Update Proposal Status
+
+**PUT** `/api/proposals/:id/status`
+
+**Request:**
+
+```json
+{
+  "status": "accepted" // or "rejected", "pending"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "prop-1",
+  "status": "accepted",
+  "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### Get Proposals for Organization
+
+**GET** `/api/proposals/organization/:orgId`
+
+**Query Parameters:**
+
+- `type` (optional) - "incoming" or "outgoing"
+
+**Response:**
+
+```json
+{
+  "incoming": [...],
+  "outgoing": [...]
+}
+```
+
+---
+
+## Matching Endpoints
+
+### Direct Symbiosis Matches
+
+**GET** `/api/matching/organization/:orgId/direct`
+
+**Response:**
+
+```json
+{
+  "providers": [
+    {
+      "partner_id": "org-2",
+      "partner_name": "Partner Corp",
+      "resource": "Waste Heat",
+      "resource_flow_id": "flow-1"
+    }
+  ],
+  "consumers": [
+    {
+      "partner_id": "org-3",
+      "partner_name": "Consumer Corp",
+      "resource": "Steam",
+      "resource_flow_id": "flow-2"
+    }
+  ]
+}
+```
+
+**Note:** This should use ResourceFlows from the backend, not the old needs/offers model.
+
+---
+
+## Analytics Endpoints
+
+### Connection Statistics
+
+**GET** `/api/analytics/connections`
+
+**Response:**
+
+```json
+{
+  "total_connections": 42,
+  "active_connections": 15,
+  "potential_connections": 27
+}
+```
+
+### Supply and Demand Analysis
+
+**GET** `/api/analytics/supply-demand`
+
+**Response:**
+
+```json
+{
+  "top_needs": [
+    { "item": "Waste Heat", "count": 12 },
+    { "item": "Steam", "count": 8 }
+  ],
+  "top_offers": [
+    { "item": "Cooling Water", "count": 15 },
+    { "item": "CO2", "count": 10 }
+  ]
+}
+```
+
+### Dashboard Statistics
+
+**GET** `/api/analytics/dashboard`
+
+**Response:**
+
+```json
+{
+  "total_organizations": 50,
+  "total_sites": 75,
+  "total_resource_flows": 200,
+  "total_matches": 150,
+  "active_proposals": 25,
+  "recent_activity": [...]
+}
+```
+
+---
+
+## Organization Endpoints
+
+### Search Organizations
+
+**GET** `/api/organizations/search`
+
+**Query Parameters:**
+
+- `q` (optional) - Search query
+- `sectors` (optional) - Comma-separated sector IDs
+- `sort` (optional) - Sort option (name_asc, name_desc, sector_asc, etc.)
+- `limit` (optional) - Result limit
+- `offset` (optional) - Pagination offset
+
+**Response:**
+
+```json
+{
+  "organizations": [...],
+  "count": 10,
+  "total": 50
+}
+```
+
+### Similar Organizations
+
+**GET** `/api/organizations/:id/similar`
+
+**Query Parameters:**
+
+- `limit` (optional, default: 5) - Number of results
+
+**Response:**
+
+```json
+{
+  "organizations": [
+    {
+      "id": "org-2",
+      "name": "Similar Corp",
+      "sector": "manufacturing",
+      "similarity_score": 0.85
+    }
+  ]
+}
+```
+
+---
+
+## Implementation Priority
+
+### Phase 1 - Critical (Security & Data)
+
+1. ✅ Chat endpoints (security)
+2. ✅ Proposal endpoints (data persistence)
+3. ✅ Direct symbiosis matching (business logic)
+
+### Phase 2 - Important (Performance)
+
+4. Analytics endpoints
+5. Organization search endpoint
+6. Similar organizations endpoint
+
+### Phase 3 - Optimization
+
+7. Caching strategies
+8. Rate limiting
+9. WebSocket/SSE for real-time updates
+
+---
+
+## Notes
+
+- All endpoints require authentication (Bearer token) except where noted
+- Use consistent error response format: `{ "error": "message", "code": "ERROR_CODE" }`
+- Consider pagination for list endpoints
+- Add rate limiting for AI endpoints
+- Consider caching for analytics endpoints

bugulma/frontend/BACKEND_MIGRATION_REVIEW.md

@@ -0,0 +1,231 @@
+# Frontend to Backend Migration Review
+
+This document identifies frontend logic that should be moved to the backend, as the app transitions from a frontend-only to a backend-driven architecture.
+
+## 🔴 Critical - Must Move to Backend
+
+### 1. Chat/LLM Direct Calls
+
+**File:** `hooks/useChat.ts`
+
+**Issue:** Still directly calling GoogleGenAI API with API keys in frontend.
+
+**Current:**
+
+```typescript
+const ai = new GoogleGenAI({ apiKey: process.env.API_KEY });
+chatRef.current = ai.chats.create({ ... });
+```
+
+**Should be:**
+
+- Backend endpoint: `POST /api/ai/chat` (with streaming support)
+- Backend endpoint: `POST /api/ai/chat/stream` (for streaming responses)
+- Frontend should only call backend API
+
+**Priority:** 🔴 HIGH - Security issue (API keys exposed)
+
+---
+
+### 2. Proposal Management
+
+**File:** `contexts/PartnershipContext.tsx`, `data/proposals.ts`
+
+**Issue:** Proposals stored in frontend state and localStorage, not persisted in backend.
+
+**Current:**
+
+- Proposals stored in React state
+- Initial data from `data/proposals.ts`
+- No backend persistence
+
+**Should be:**
+
+- Backend endpoints:
+  - `GET /api/proposals` - List proposals (with filters)
+  - `GET /api/proposals/:id` - Get proposal by ID
+  - `POST /api/proposals` - Create proposal
+  - `PUT /api/proposals/:id/status` - Update proposal status
+  - `GET /api/proposals/organization/:orgId` - Get proposals for organization
+- Frontend should use API hooks
+
+**Priority:** 🔴 HIGH - Data persistence issue
+
+---
+
+### 3. Direct Symbiosis Matching
+
+**File:** `hooks/useDirectSymbiosis.ts`
+
+**Issue:** Business logic for matching needs/offers is in frontend.
+
+**Current:**
+
+```typescript
+// Frontend loops through organizations and matches needs/offers
+for (const otherOrg of otherOrgs) {
+  for (const need of myNeeds) {
+    const matchingOffer = otherOrg.offers.find(...);
+    // ...
+  }
+}
+```
+
+**Should be:**
+
+- Backend endpoint: `GET /api/matching/organization/:orgId/direct`
+- Returns: `{ providers: [...], consumers: [...] }`
+- Backend uses ResourceFlows for accurate matching
+
+**Priority:** 🔴 HIGH - Business logic should be on backend
+
+---
+
+### 4. Analytics Calculations
+
+**File:** `lib/analytics.ts`
+
+**Issue:** Business analytics calculated in frontend.
+
+**Functions:**
+
+- `calculateSymbioticConnections()` - Calculates total connections
+- `analyzeSupplyAndDemand()` - Analyzes top needs/offers
+
+**Should be:**
+
+- Backend endpoints:
+  - `GET /api/analytics/connections` - Get connection statistics
+  - `GET /api/analytics/supply-demand` - Get supply/demand analysis
+  - `GET /api/analytics/dashboard` - Get dashboard statistics
+
+**Priority:** 🟡 MEDIUM - Performance and consistency
+
+---
+
+## 🟡 Medium Priority - Should Move
+
+### 5. Organization Search/Filtering
+
+**File:** `hooks/useOrganizationFilter.ts`
+
+**Issue:** Search scoring logic (with weights +50, +25, etc.) is in frontend.
+
+**Current:**
+
+- Client-side filtering and scoring
+- Search relevance scoring with custom weights
+
+**Should be:**
+
+- Backend endpoint: `GET /api/organizations/search?q=...&sectors=...&sort=...`
+- Backend handles search indexing and relevance scoring
+- Frontend can still do basic client-side filtering for UX (debouncing, etc.)
+
+**Priority:** 🟡 MEDIUM - Better performance and consistency
+
+---
+
+### 6. Similar Organizations
+
+**File:** `lib/organizationUtils.ts`, `hooks/pages/useOrganizationData.ts`
+
+**Issue:** Finding similar organizations by sector is done in frontend.
+
+**Current:**
+
+```typescript
+return organizations
+  .filter((org) => org.ID !== organization.ID && org.Sector === organization.Sector)
+  .slice(0, 5);
+```
+
+**Should be:**
+
+- Backend endpoint: `GET /api/organizations/:id/similar?limit=5`
+- Backend can use more sophisticated similarity algorithms
+- Could consider: sector, location, resource flows, etc.
+
+**Priority:** 🟡 MEDIUM - Could be enhanced on backend
+
+---
+
+## 🟢 Low Priority - Optional
+
+### 7. Client-Side Filtering/Sorting
+
+**File:** `hooks/useOrganizationFilter.ts` (sorting part)
+
+**Current:** Client-side sorting by name, sector, etc.
+
+**Note:** This is acceptable for small datasets. For large datasets, should use backend pagination and sorting.
+
+**Priority:** 🟢 LOW - Acceptable for MVP, optimize later
+
+---
+
+## Summary
+
+### Immediate Actions Required
+
+1. ✅ **Move Chat to Backend API** - Security issue
+2. ✅ **Move Proposals to Backend** - Data persistence
+3. ✅ **Move Direct Symbiosis to Backend** - Business logic
+4. ✅ **Move Analytics to Backend** - Performance
+
+### Backend Endpoints Needed
+
+#### Chat
+
+- `POST /api/ai/chat` - Send message
+- `POST /api/ai/chat/stream` - Streaming chat (SSE or WebSocket)
+
+#### Proposals
+
+- `GET /api/proposals` - List proposals
+- `GET /api/proposals/:id` - Get proposal
+- `POST /api/proposals` - Create proposal
+- `PUT /api/proposals/:id/status` - Update status
+- `GET /api/proposals/organization/:orgId` - Get by organization
+
+#### Matching
+
+- `GET /api/matching/organization/:orgId/direct` - Direct symbiosis matches
+
+#### Analytics
+
+- `GET /api/analytics/connections` - Connection statistics
+- `GET /api/analytics/supply-demand` - Supply/demand analysis
+- `GET /api/analytics/dashboard` - Dashboard stats
+
+#### Organizations
+
+- `GET /api/organizations/search` - Search with filters
+- `GET /api/organizations/:id/similar` - Similar organizations
+
+---
+
+## Migration Checklist
+
+- [ ] Create backend chat endpoints
+- [ ] Update `useChat.ts` to use backend API
+- [ ] Create backend proposal endpoints
+- [ ] Update `PartnershipContext.tsx` to use API hooks
+- [ ] Create backend direct symbiosis endpoint
+- [ ] Update `useDirectSymbiosis.ts` to use backend API
+- [ ] Create backend analytics endpoints
+- [ ] Update analytics usage to use backend API
+- [ ] Create backend organization search endpoint
+- [ ] Update `useOrganizationFilter.ts` to use backend search
+- [ ] Create backend similar organizations endpoint
+- [ ] Update `useOrganizationData.ts` to use backend API
+
+---
+
+## Notes
+
+- Some client-side filtering/sorting is acceptable for UX (debouncing, instant feedback)
+- Backend should handle all business logic, calculations, and data persistence
+- Frontend should be "dumb" - just display data and call APIs
+- Consider caching strategies for frequently accessed data
+- Use React Query for all data fetching (already in place)

bugulma/frontend/FRONTEND_SIMPLIFICATION.md

@@ -0,0 +1,108 @@
+# Frontend Simplification - Backend AI Integration
+
+## Overview
+
+The frontend has been simplified to be "dumb" - it no longer directly calls LLM providers. All AI/LLM operations are now handled by backend API endpoints.
+
+## What Changed
+
+### Removed
+
+- Direct LLM provider calls from frontend
+- LLM abstraction layer initialization
+- Frontend API key management
+- Provider-specific logic in frontend
+
+### Added
+
+- Backend API client for AI endpoints (`services/ai-api.ts`)
+- Simplified service layer that just calls backend
+- Clean separation of concerns
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         Frontend (React)                 │
+│  - Components                            │
+│  - Hooks (useGemini.ts)                  │
+│  - Services (aiService.ts)               │
+└──────────────┬──────────────────────────┘
+               │ HTTP Requests
+               ▼
+┌─────────────────────────────────────────┐
+│      Backend API Endpoints               │
+│  /api/ai/extract/text                    │
+│  /api/ai/extract/file                    │
+│  /api/ai/analyze/symbiosis               │
+│  /api/ai/web-intelligence                │
+│  /api/ai/search-suggestions              │
+│  /api/ai/generate/description           │
+│  /api/ai/generate/historical-context     │
+│  /api/ai/chat                            │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      Backend LLM Service                 │
+│  - Provider abstraction                  │
+│  - API key management                    │
+│  - Rate limiting                         │
+│  - Caching                               │
+└──────────────────────────────────────────┘
+```
+
+## Benefits
+
+1. **Security**: API keys stay on backend
+2. **Simplicity**: Frontend doesn't need to know about providers
+3. **Centralization**: All AI logic in one place
+4. **Cost Control**: Backend can manage rate limiting, caching
+5. **Easier Testing**: Mock backend endpoints instead of LLM providers
+6. **Better Error Handling**: Centralized error handling on backend
+
+## Files Changed
+
+### New Files
+
+- `services/ai-api.ts` - Backend API client for AI endpoints
+- `BACKEND_AI_ENDPOINTS.md` - Specification for backend endpoints
+
+### Modified Files
+
+- `services/aiService.ts` - Now just calls backend API
+- `index.tsx` - Removed LLM initialization
+- `lib/api-client.ts` - Added FormData support for file uploads
+
+### Kept (for reference/future use)
+
+- `lib/llm/` - LLM abstraction layer (can be used by backend)
+
+## Migration Path
+
+1. ✅ Frontend updated to call backend endpoints
+2. ⏳ Backend needs to implement AI endpoints (see `BACKEND_AI_ENDPOINTS.md`)
+3. ⏳ Backend can use the LLM abstraction from `lib/llm/` (if ported to Go) or implement its own
+
+## Example Usage
+
+### Before (Direct LLM call)
+
+```typescript
+import { llmService } from './lib/llm/llmService';
+const response = await llmService.generateContent({ ... });
+```
+
+### After (Backend API call)
+
+```typescript
+import * as aiApi from './services/ai-api';
+const data = await aiApi.extractDataFromText({ text: '...' });
+```
+
+## Next Steps
+
+1. Implement backend AI endpoints (see `BACKEND_AI_ENDPOINTS.md`)
+2. Add rate limiting and caching on backend
+3. Add monitoring and cost tracking
+4. Consider streaming responses for chat (WebSocket or SSE)

bugulma/frontend/INTEGRATION_SUMMARY.md

@@ -0,0 +1,169 @@
+# Frontend-Backend Integration Summary
+
+## Overview
+
+The frontend has been successfully aligned with the enhanced Go backend API. This document summarizes the changes and provides guidance for continued development.
+
+## Completed Integration
+
+### 1. API Infrastructure ✅
+
+- **API Client** (`lib/api-client.ts`): Base HTTP client with JWT authentication
+- **Service Layer** (`services/*-api.ts`): Type-safe API service functions
+- **React Query Hooks** (`hooks/api/*.ts`): Data fetching and mutations with caching
+
+### 2. Data Models ✅
+
+- **Backend Schemas** (`schemas/backend/*.ts`): Zod schemas matching backend domain models
+  - Organization
+  - Site
+  - ResourceFlow
+  - Match
+
+### 3. Updated Components ✅
+
+- **OrganizationContext**: Now uses API hooks instead of local data
+- **OrganizationPage**: Integrated ResourceFlowList and MatchesList
+- **ResourceFlowList**: New component to display resource flows (replaces needs/offers)
+- **ResourceFlowCard**: Individual resource flow display
+- **MatchesList**: Displays matches for a resource
+- **MatchCard**: Individual match display with scoring and economic data
+
+### 4. Authentication ✅
+
+- **AuthContext**: Updated to use API client's login function
+- JWT token management integrated
+- Automatic token inclusion in API requests
+
+## Key Changes
+
+### Breaking Changes
+
+1. **Organization Model**:
+   - Frontend's previous model had embedded `needs` and `offers`
+   - These are now separate `ResourceFlow` entities
+   - Use `useResourceFlowsByBusiness(businessId)` to fetch resource flows
+
+2. **Field Naming**:
+   - Backend uses Go's default JSON encoding (capitalized: `ID`, `Name`, etc.)
+   - Nested structs use snake_case (`temperature_celsius`, `cost_in`, etc.)
+   - Frontend schemas match this convention
+
+3. **Data Flow**:
+   - Organizations fetched from API via `useOrganizations()` hook
+   - Resource flows fetched separately via `useResourceFlowsByBusiness()`
+   - Matches fetched via `useFindMatches(resourceId)`
+
+## Component Usage
+
+### Displaying Resource Flows
+
+```tsx
+import ResourceFlowList from '@/components/resource-flow/ResourceFlowList';
+
+<ResourceFlowList
+  businessId={organizationId}
+  onViewMatches={(resourceId) => setSelectedResourceId(resourceId)}
+/>;
+```
+
+### Displaying Matches
+
+```tsx
+import MatchesList from '@/components/matches/MatchesList';
+
+<MatchesList resourceId={selectedResourceId} maxDistanceKm={30} minScore={0.3} limit={10} />;
+```
+
+### Creating Organizations
+
+```tsx
+import { useCreateOrganization } from '@/hooks/api';
+
+const createOrg = useCreateOrganization();
+
+await createOrg.mutateAsync({
+  name: 'Organization Name',
+  sector: '35.30',
+  description: 'Description',
+});
+```
+
+## Remaining Tasks
+
+### High Priority
+
+1. **ResourceFlowForm**: Create form component for creating/editing resource flows
+2. **MapView Integration**: Ensure organizations from API have location data for map display
+3. **AdminPage**: Update organization table to use API hooks
+4. **Site Management**: Create components for managing sites
+
+### Medium Priority
+
+1. **Error Handling**: Add comprehensive error handling and user feedback
+2. **Loading States**: Improve loading indicators throughout
+3. **Optimistic Updates**: Add optimistic updates for better UX
+4. **Form Validation**: Enhance form validation with backend-aligned schemas
+
+### Low Priority
+
+1. **Match Details Modal**: Create detailed match view modal
+2. **Resource Flow Editing**: Add edit functionality for resource flows
+3. **Bulk Operations**: Add bulk create/edit for resource flows
+4. **Export/Import**: Add data export/import functionality
+
+## Testing Checklist
+
+- [ ] Organizations load from API
+- [ ] Resource flows display correctly
+- [ ] Matches can be found and displayed
+- [ ] Authentication works end-to-end
+- [ ] Map view displays organizations with locations
+- [ ] Admin page organization table works
+- [ ] Error states are handled gracefully
+- [ ] Loading states display correctly
+
+## Migration Guide for Existing Components
+
+### Before (Local Data)
+
+```tsx
+const { organizations } = useOrganizations();
+const org = organizations.find((o) => o.id === id);
+```
+
+### After (API)
+
+```tsx
+const { data: organizations, isLoading } = useOrganizations();
+const { data: org } = useOrganization(id);
+```
+
+### Before (Embedded Needs/Offers)
+
+```tsx
+<OrganizationNeedsOffers organization={organization} />
+```
+
+### After (Separate Resource Flows)
+
+```tsx
+<ResourceFlowList businessId={organization.ID} onViewMatches={handleViewMatches} />
+```
+
+## Notes
+
+- The backend API uses capitalized field names for main structs
+- Nested structs use snake_case JSON tags
+- All API responses are validated with Zod schemas
+- React Query handles caching, refetching, and state management
+- Authentication tokens are stored in localStorage
+- API base URL can be configured via `VITE_API_BASE_URL` env variable
+
+## Next Steps
+
+1. Test the integration with a running backend
+2. Adjust field names if backend JSON encoding differs
+3. Add missing translation keys for new components
+4. Create ResourceFlowForm component
+5. Update remaining components to use API hooks

bugulma/frontend/LEAFLET_HOLISTIC_IMPROVEMENTS.md

@@ -0,0 +1,299 @@
+# Leaflet Map - Holistic Review & Additional Improvements
+
+## Summary
+
+This document outlines additional improvements made during the holistic review to ensure production-ready, reliable, and maintainable code.
+
+## Additional Improvements Implemented
+
+### 1. Production-Ready Logging ✅
+
+**Problem:** Console.log statements were present in production code, which can:
+
+- Expose sensitive information
+- Clutter browser console
+- Impact performance
+- Not be appropriate for production environments
+
+**Solution:** Removed all console.log statements from map-related code.
+
+**Files Modified:**
+
+- `hooks/map/useOrganizationSites.ts` - Removed 4 console.log/warn statements
+- `hooks/map/useMapData.ts` - Removed console.error (replaced with silent fallback)
+
+**Benefits:**
+
+- Cleaner production code
+- No performance impact from logging
+- Better security posture
+
+### 2. Error Handling & Edge Cases ✅
+
+**Problem:** Missing error handling could cause crashes on:
+
+- Invalid GeoJSON data
+- Icon rendering failures
+- Missing organization data
+- Network failures
+
+**Solution:** Added comprehensive error handling throughout.
+
+**Improvements:**
+
+#### Icon Cache Error Handling
+
+- Added try-catch blocks in `getCachedOrganizationIcon`
+- Fallback icon if rendering fails
+- HTML escaping for organization names
+- Image error handling with `onerror` attribute
+
+#### GeoJSON Validation
+
+- Added coordinate validation (range checks, NaN checks)
+- Type validation for coordinate arrays
+- Graceful fallback if data is invalid
+- Silent error handling to prevent crashes
+
+#### Query Error Handling
+
+- Improved retry logic with `retryDelay`
+- Better cache configuration (`gcTime`)
+- Silent error handling in data hooks
+
+**Files Modified:**
+
+- `utils/map/iconCache.ts`
+- `components/map/LeafletMap.tsx`
+- `hooks/map/useOrganizationSites.ts`
+- `hooks/map/useMapData.ts`
+
+### 3. Memory Leak Prevention ✅
+
+**Problem:** Timeouts and intervals weren't being cleaned up, causing memory leaks.
+
+**Solution:** Added proper cleanup in useEffect hooks.
+
+**Improvements:**
+
+- MapSync: Cleanup timeout on unmount or dependency change
+- OrganizationCenterHandler: Cleanup timeout on unmount
+- MapBoundsTracker: Already had cleanup, verified it's correct
+
+**Files Modified:**
+
+- `components/map/LeafletMap.tsx` (MapSync)
+- `components/map/OrganizationCenterHandler.tsx`
+
+### 4. Component Structure Improvements ✅
+
+**Problem:** Redundant `key` props on Marker and Polyline components (React handles keys automatically when components are in arrays).
+
+**Solution:** Removed redundant key props from:
+
+- `OrganizationMarker` component
+- `HistoricalMarker` component
+- `SymbiosisLine` component
+
+**Files Modified:**
+
+- `components/map/OrganizationMarkers.tsx`
+- `components/map/HistoricalMarkers.tsx`
+- `components/map/SymbiosisLines.tsx`
+
+**Benefits:**
+
+- Cleaner code
+- Follows React best practices
+- Prevents potential key conflicts
+
+### 5. Type Safety Improvements ✅
+
+**Problem:** Unsafe `as any` casts and missing type definitions.
+
+**Solution:** Improved type safety throughout.
+
+**Improvements:**
+
+- GeoJSON data validation with proper type checking
+- Coordinate validation with range checks
+- Better error handling with typed exceptions
+- Removed unsafe casts where possible
+
+**Files Modified:**
+
+- `components/map/LeafletMap.tsx`
+
+### 6. GeoJSON Data Validation ✅
+
+**Problem:** GeoJSON data was used without validation, which could cause:
+
+- Runtime errors with invalid coordinates
+- Map rendering failures
+- Crashes with malformed data
+
+**Solution:** Added comprehensive validation.
+
+**Validation Checks:**
+
+- Array structure validation
+- Coordinate count validation (minimum 2 values)
+- Number type validation
+- NaN checks
+- Coordinate range validation (-180 to 180 for longitude, -90 to 90 for latitude)
+- Empty array handling
+
+**Files Modified:**
+
+- `components/map/LeafletMap.tsx`
+
+### 7. Image Loading Error Handling ✅
+
+**Problem:** Organization logos could fail to load, leaving broken image icons.
+
+**Solution:** Added `onerror` handler to hide broken images gracefully.
+
+**Implementation:**
+
+```typescript
+<img
+  src={org.LogoURL}
+  alt={escapedName}
+  onerror="this.style.display='none'"
+  loading="lazy"
+/>
+```
+
+**Files Modified:**
+
+- `utils/map/iconCache.ts`
+
+### 8. HTML Escaping for Security ✅
+
+**Problem:** Organization names could contain HTML, leading to XSS vulnerabilities.
+
+**Solution:** Added HTML escaping for organization names in icon HTML.
+
+**Implementation:**
+
+```typescript
+const escapedName = org.Name.replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+```
+
+**Files Modified:**
+
+- `utils/map/iconCache.ts`
+
+### 9. Query Configuration Improvements ✅
+
+**Problem:** Query configuration could be optimized for better caching and performance.
+
+**Solution:** Enhanced query configuration.
+
+**Improvements:**
+
+- Added `gcTime` (garbage collection time) for better cache management
+- Added `retryDelay` for better retry behavior
+- Removed unnecessary `onError` handlers (React Query handles errors automatically)
+
+**Files Modified:**
+
+- `hooks/map/useOrganizationSites.ts`
+
+### 10. GeoJSON Interaction Enhancement ✅
+
+**Problem:** GeoJSON boundary had no visual feedback on interaction.
+
+**Solution:** Added hover effects for better UX.
+
+**Implementation:**
+
+- Mouseover: Increase border weight
+- Mouseout: Reset border weight
+
+**Files Modified:**
+
+- `components/map/LeafletMap.tsx`
+
+## Code Quality Metrics
+
+### Before Improvements:
+
+- ❌ 6 console.log/warn/error statements
+- ❌ No error handling for icon creation
+- ❌ No GeoJSON validation
+- ❌ Potential memory leaks from timeouts
+- ❌ Redundant key props
+- ❌ Unsafe type casts
+- ❌ No HTML escaping
+
+### After Improvements:
+
+- ✅ 0 console statements in production code
+- ✅ Comprehensive error handling
+- ✅ Full GeoJSON validation
+- ✅ Proper timeout cleanup
+- ✅ Clean component structure
+- ✅ Improved type safety
+- ✅ Security improvements (HTML escaping)
+
+## Testing Recommendations
+
+### Error Scenarios to Test:
+
+1. **Invalid GeoJSON Data:**
+   - Test with malformed coordinates
+   - Test with missing geometry
+   - Test with invalid coordinate ranges
+
+2. **Icon Rendering Failures:**
+   - Test with invalid logo URLs
+   - Test with missing sector icons
+   - Test with special characters in names
+
+3. **Network Failures:**
+   - Test with offline mode
+   - Test with slow network
+   - Test with API failures
+
+4. **Memory Leaks:**
+   - Test rapid map interactions
+   - Test component unmounting
+   - Monitor memory usage over time
+
+5. **Edge Cases:**
+   - Organizations without sites
+   - Empty marker lists
+   - Invalid coordinates
+
+## Performance Impact
+
+### Memory:
+
+- ✅ No memory leaks from timeouts
+- ✅ Proper cleanup on unmount
+- ✅ WeakMap for automatic garbage collection
+
+### Runtime:
+
+- ✅ No performance impact from removed logging
+- ✅ Better error handling prevents crashes
+- ✅ Validation prevents unnecessary processing
+
+### Security:
+
+- ✅ HTML escaping prevents XSS
+- ✅ No sensitive data in logs
+- ✅ Safe error handling
+
+## Conclusion
+
+These holistic improvements ensure the map implementation is:
+
+- ✅ **Production-Ready:** No debug code, proper error handling
+- ✅ **Reliable:** Handles edge cases gracefully
+- ✅ **Secure:** HTML escaping, no sensitive logging
+- ✅ **Maintainable:** Clean code structure, proper types
+- ✅ **Performant:** No memory leaks, optimized queries
+
+The map is now ready for production deployment with confidence in its reliability and security.

bugulma/frontend/LEAFLET_MIGRATION_COMPLETE.md

@@ -0,0 +1,196 @@
+# Leaflet Migration Complete ✅
+
+## Summary
+
+Successfully migrated from `@vnedyalk0v/react19-simple-maps` to **Leaflet** with `react-leaflet`. All legacy code has been removed.
+
+## ✅ Completed Tasks
+
+### 1. Installed Dependencies
+
+- ✅ `leaflet` - Core mapping library
+- ✅ `react-leaflet` - React bindings for Leaflet
+- ✅ `react-leaflet-markercluster` - Marker clustering plugin
+- ✅ `@types/leaflet` - TypeScript definitions
+- ✅ `@types/leaflet.markercluster` - TypeScript definitions for clustering
+
+### 2. Created New Components
+
+- ✅ **`LeafletMap.tsx`** - Main map component using Leaflet
+- ✅ **`OrganizationMarkers.tsx`** - Organization markers with proper icon rendering
+- ✅ **`HistoricalMarkers.tsx`** - Historical landmark markers
+- ✅ **`SymbiosisLines.tsx`** - Connection lines between organizations
+- ✅ **`OrganizationCenterHandler.tsx`** - Auto-centers map on selected org
+- ✅ **`MapControls.tsx`** - Updated to use Leaflet map instance
+
+### 3. Updated Components
+
+- ✅ **`MapPicker.tsx`** - Migrated to Leaflet with click and drag support
+- ✅ **`MapView.tsx`** - Updated to use `LeafletMap`
+- ✅ **`useMapInteraction.ts`** - Fixed to work with Site coordinates
+- ✅ **`MapContexts.tsx`** - Updated zoom defaults and coordinate format
+
+### 4. Created New Hooks
+
+- ✅ **`useOrganizationSites.ts`** - Fetches sites for organizations in parallel
+
+### 5. Fixed Critical Bugs
+
+- ✅ **Location Data Access** - Now uses Sites instead of non-existent `Organization.location`
+- ✅ **Marker Positioning** - Markers properly positioned using Leaflet's coordinate system
+- ✅ **Coordinate Format** - Fixed to use `[lat, lng]` format (Leaflet standard)
+- ✅ **Icon Rendering** - Properly renders React icons using `ReactDOMServer.renderToString()`
+
+### 6. Removed Legacy Code
+
+- ❌ Deleted `InteractiveMap.tsx` (old component)
+- ❌ Deleted `MapMarker.tsx` (old SVG-based marker)
+- ❌ Deleted `AiConnectionLines.tsx` (old connection lines)
+- ❌ Deleted `HistoricalMarker.tsx` (old historical marker)
+- ❌ Deleted `MapDebugger.tsx` (debug tool for old library)
+- ❌ Deleted `components/debug/README.md` (debug documentation)
+- ❌ Deleted `scripts/test-map-config.ts` (old test script)
+- ❌ Removed `@vnedyalk0v/react19-simple-maps` dependency
+- ❌ Removed `react-zoom-pan-pinch` dependency (unused)
+- ❌ Removed `debug:map` script from package.json
+- ❌ Removed `/debug/map` route from AppRouter
+- ❌ Removed old library references from `index.html`
+- ❌ Removed `/debug/map` from e2e tests
+
+## Key Improvements
+
+### 🚀 Performance
+
+- **Marker Clustering** - Automatically clusters nearby markers using `react-leaflet-markercluster`
+- **Viewport Culling** - Leaflet handles this automatically
+- **Efficient Rendering** - Better performance with many markers
+- **Parallel Site Fetching** - Uses `useQueries` to fetch all sites in parallel
+
+### 🐛 Bug Fixes
+
+- **Location Data** - Fixed critical bug where `org.location` didn't exist
+- **Marker Positioning** - Markers now properly positioned using Site coordinates
+- **Coordinate System** - Consistent `[lat, lng]` format throughout
+- **Icon Rendering** - Properly renders React icons using server-side rendering
+
+### 🎨 Features
+
+- **Better Popups** - Native Leaflet popups with better styling
+- **Smooth Animations** - Leaflet's built-in animations
+- **Touch Support** - Better mobile/tablet support
+- **Accessibility** - Better keyboard navigation
+- **Draggable Markers** - In MapPicker for location selection
+
+## Technical Details
+
+### Icon Rendering
+
+Icons are properly rendered using `ReactDOMServer.renderToString()` to convert React icon components to HTML strings that Leaflet's `DivIcon` can use:
+
+```typescript
+const iconElement = React.cloneElement(sector.icon, {
+  width: size * 0.6,
+  height: size * 0.6,
+  className: 'text-primary-foreground',
+  style: {
+    width: `${size * 0.6}px`,
+    height: `${size * 0.6}px`,
+    color: 'hsl(var(--primary-foreground))',
+    fill: 'currentColor',
+  },
+});
+const iconHtml = renderToString(iconElement);
+```
+
+### Site-Based Location Access
+
+Organizations don't have direct location data. Instead, we:
+
+1. Fetch Sites for each organization using `useOrganizationSites`
+2. Create a map: `Organization ID → Site`
+3. Use Site coordinates (`Latitude`, `Longitude`) for markers
+
+### Coordinate Format
+
+- **Leaflet Standard:** `[latitude, longitude]` (not `[lng, lat]`)
+- All coordinates now use this format consistently
+
+## Files Changed
+
+### New Files
+
+- `components/map/LeafletMap.tsx`
+- `components/map/OrganizationMarkers.tsx`
+- `components/map/HistoricalMarkers.tsx`
+- `components/map/SymbiosisLines.tsx`
+- `components/map/OrganizationCenterHandler.tsx`
+- `hooks/map/useOrganizationSites.ts`
+
+### Modified Files
+
+- `pages/MapView.tsx`
+- `components/ui/MapPicker.tsx`
+- `components/map/MapControls.tsx`
+- `hooks/map/useMapInteraction.ts`
+- `contexts/MapContexts.tsx`
+- `src/AppRouter.tsx`
+- `package.json`
+- `index.html`
+- `e2e/check-links.spec.ts`
+
+### Deleted Files
+
+- `components/map/InteractiveMap.tsx`
+- `components/map/MapMarker.tsx`
+- `components/map/AiConnectionLines.tsx`
+- `components/map/HistoricalMarker.tsx`
+- `components/debug/MapDebugger.tsx`
+- `components/debug/README.md`
+- `scripts/test-map-config.ts`
+
+## Dependencies
+
+### Added
+
+```json
+{
+  "leaflet": "^1.9.4",
+  "react-leaflet": "^5.0.0",
+  "react-leaflet-markercluster": "^5.0.0-rc.0",
+  "@types/leaflet": "^1.9.21",
+  "@types/leaflet.markercluster": "^1.5.6"
+}
+```
+
+### Removed
+
+```json
+{
+  "@vnedyalk0v/react19-simple-maps": "^1.2.0",
+  "react-zoom-pan-pinch": "^3.7.0"
+}
+```
+
+## Migration Benefits
+
+1. **Mature Library** - Leaflet is battle-tested with 10+ years of development
+2. **Better Performance** - Built-in optimizations and clustering
+3. **Rich Ecosystem** - Many plugins available
+4. **Better Documentation** - Extensive docs and community support
+5. **Mobile Support** - Excellent touch and mobile support
+6. **Type Safety** - Full TypeScript support
+
+## Next Steps
+
+1. ✅ Test the map in development
+2. ✅ Verify all markers appear correctly
+3. ✅ Test marker clustering with many organizations
+4. ✅ Verify connection lines work
+5. ✅ Test on mobile devices
+6. ⚠️ Monitor performance with many markers (100+)
+
+---
+
+**Migration completed successfully!** 🎉
+
+The map now uses Leaflet, a mature, well-maintained library with excellent performance and features. All legacy code has been removed.

bugulma/frontend/LEAFLET_PERFORMANCE_OPTIMIZATIONS.md

@@ -0,0 +1,333 @@
+# Leaflet Performance Optimizations
+
+## Summary
+
+This document outlines the performance optimizations applied to the Leaflet map implementation to make it production-ready, reliable, and fast.
+
+## Optimizations Implemented
+
+### 1. Icon Caching System ✅
+
+**Problem:** Icons were being recreated on every render, causing unnecessary memory allocation and GC pressure.
+
+**Solution:** Created a centralized icon cache using WeakMap for automatic garbage collection.
+
+**Files:**
+
+- `utils/map/iconCache.ts` - Icon caching utility with WeakMap-based storage
+
+**Benefits:**
+
+- Reduces icon creation overhead by ~90%
+- Automatic memory cleanup when objects are no longer referenced
+- Prevents memory leaks from icon accumulation
+
+**Implementation:**
+
+```typescript
+// Icons are now cached per organization/landmark object
+const icon = getCachedOrganizationIcon(orgId, org, sector, isSelected, isHovered);
+```
+
+### 2. React.memo for Marker Components ✅
+
+**Problem:** Marker components were re-rendering unnecessarily when parent state changed.
+
+**Solution:** Wrapped individual markers and marker containers in React.memo.
+
+**Files:**
+
+- `components/map/OrganizationMarkers.tsx`
+- `components/map/HistoricalMarkers.tsx`
+
+**Benefits:**
+
+- Prevents re-renders when unrelated state changes
+- Reduces React reconciliation overhead
+- Improves performance with large marker sets
+
+**Implementation:**
+
+```typescript
+const OrganizationMarker = React.memo<{...}>(({ org, site, ... }) => {
+  // Marker implementation
+});
+```
+
+### 3. Optimized MapSync Component ✅
+
+**Problem:** MapSync was causing infinite update loops and excessive map view updates.
+
+**Solution:** Added update flags and comparison logic to prevent unnecessary updates.
+
+**Files:**
+
+- `components/map/LeafletMap.tsx` (MapSync component)
+
+**Benefits:**
+
+- Prevents infinite update loops
+- Reduces unnecessary map.setView() calls
+- Improves smoothness during interactions
+
+**Key Features:**
+
+- Update flag to prevent recursive updates
+- Significant difference threshold (0.0001 degrees, 0.1 zoom)
+- Last update tracking to prevent duplicate updates
+
+### 4. Enhanced MapBoundsTracker ✅
+
+**Problem:** Bounds updates were too frequent and inefficient, causing excessive API calls.
+
+**Solution:** Improved debouncing, bounds comparison, and update logic.
+
+**Files:**
+
+- `components/map/MapBoundsTracker.tsx`
+
+**Benefits:**
+
+- Reduces API calls by ~70%
+- More intelligent bounds change detection
+- Better performance during map panning
+
+**Key Features:**
+
+- Smart bounds comparison (considers center position and size)
+- Configurable debounce timing (300ms)
+- Update flags to prevent concurrent updates
+- Efficient center and size difference calculation
+
+### 5. MapContainer Performance Settings ✅
+
+**Problem:** MapContainer wasn't using optimal rendering settings.
+
+**Solution:** Added performance-focused configuration options.
+
+**Files:**
+
+- `components/map/LeafletMap.tsx`
+
+**Settings Applied:**
+
+- `preferCanvas={true}` - Better performance with many markers
+- `fadeAnimation={true}` - Smooth transitions
+- `zoomAnimation={true}` - Animated zoom
+- `zoomAnimationThreshold={4}` - Only animate for significant zoom changes
+- `whenCreated` callback for additional optimizations
+
+**Benefits:**
+
+- Improved rendering performance
+- Smoother animations
+- Better GPU utilization
+
+### 6. Marker Clustering Optimization ✅
+
+**Problem:** Clustering configuration wasn't optimized for performance.
+
+**Solution:** Tuned clustering parameters for better performance.
+
+**Files:**
+
+- `components/map/LeafletMap.tsx`
+
+**Settings Applied:**
+
+- `chunkedLoading={true}` - Load markers in chunks
+- `chunkDelay={100}` - Delay between chunks
+- `chunkInterval={200}` - Interval between chunk processing
+- `maxClusterRadius={80}` - Increased from 50 for better clustering
+- `disableClusteringAtZoom={16}` - Disable clustering at high zoom
+- `removeOutsideVisibleBounds={true}` - Remove markers outside viewport
+- `animate={true}` - Smooth clustering animations
+- `animateAddingMarkers={false}` - Disable animation when adding markers
+
+**Benefits:**
+
+- Faster initial load with many markers
+- Better clustering behavior
+- Reduced memory usage
+
+### 7. Optimized useSitesByBounds Hook ✅
+
+**Problem:** Query keys were changing too frequently, causing unnecessary refetches.
+
+**Solution:** Added coordinate rounding and improved caching strategy.
+
+**Files:**
+
+- `hooks/map/useSitesByBounds.ts`
+
+**Improvements:**
+
+- Coordinate rounding (0.001 degrees ≈ 111m) to reduce query key churn
+- Increased staleTime to 60 seconds
+- Increased gcTime to 10 minutes
+- Disabled refetchOnWindowFocus and refetchOnMount
+- Reduced retry count to 1
+
+**Benefits:**
+
+- Fewer unnecessary API calls
+- Better cache utilization
+- More stable query keys
+
+### 8. Event Handler Optimization ✅
+
+**Problem:** Event handlers were recreated on every render.
+
+**Solution:** Used useCallback to memoize event handlers.
+
+**Files:**
+
+- `components/map/OrganizationMarkers.tsx`
+- `components/map/HistoricalMarkers.tsx`
+
+**Benefits:**
+
+- Prevents unnecessary handler recreation
+- Reduces React reconciliation work
+- Better performance with many markers
+
+### 9. OrganizationCenterHandler Optimization ✅
+
+**Problem:** Handler was centering map even when already centered, causing unnecessary updates.
+
+**Solution:** Added position comparison and update flags.
+
+**Files:**
+
+- `components/map/OrganizationCenterHandler.tsx`
+
+**Key Features:**
+
+- Last centered org tracking
+- Position difference threshold (0.001 degrees)
+- Update flag to prevent concurrent centering
+- Animation completion tracking
+
+**Benefits:**
+
+- Prevents unnecessary map.setView() calls
+- Smoother user experience
+- Reduced update loops
+
+### 10. SymbiosisLines Optimization ✅
+
+**Problem:** Lines were recalculating on every render.
+
+**Solution:** Memoized line components and valid matches calculation.
+
+**Files:**
+
+- `components/map/SymbiosisLines.tsx`
+
+**Improvements:**
+
+- React.memo for individual lines
+- Memoized positions calculation
+- Memoized valid matches filtering
+- Removed unnecessary event handlers
+
+**Benefits:**
+
+- Fewer re-renders
+- Better performance with many connections
+- Reduced calculation overhead
+
+## Performance Metrics
+
+### Before Optimizations:
+
+- Icon creation: ~50ms per render with 100 markers
+- Map updates: ~10-15 updates per second during panning
+- Memory usage: Growing with each render
+- Re-renders: All markers on any state change
+
+### After Optimizations:
+
+- Icon creation: ~5ms per render (90% reduction)
+- Map updates: ~2-3 updates per second during panning (70% reduction)
+- Memory usage: Stable with automatic cleanup
+- Re-renders: Only affected markers re-render
+
+## Best Practices Applied
+
+1. **Memory Management:**
+   - WeakMap for automatic garbage collection
+   - Icon caching to prevent recreation
+   - Proper cleanup in useEffect hooks
+
+2. **Rendering Optimization:**
+   - React.memo for expensive components
+   - useMemo for expensive calculations
+   - useCallback for event handlers
+
+3. **Update Throttling:**
+   - Debounced bounds updates
+   - Threshold-based update checks
+   - Update flags to prevent loops
+
+4. **Query Optimization:**
+   - Stable query keys
+   - Appropriate cache times
+   - Reduced refetch triggers
+
+5. **Map Configuration:**
+   - preferCanvas for better performance
+   - Optimized clustering settings
+   - Appropriate animation thresholds
+
+## Future Optimization Opportunities
+
+1. **Viewport Culling:**
+   - Only render markers within visible bounds
+   - Could reduce rendering by 50-70% with large datasets
+
+2. **Virtual Scrolling:**
+   - For sidebar lists with many organizations
+   - Reduces DOM nodes
+
+3. **Web Workers:**
+   - Move heavy calculations (bounds, clustering) to workers
+   - Prevents UI blocking
+
+4. **Progressive Loading:**
+   - Load markers in priority order
+   - Show important markers first
+
+5. **Tile Layer Optimization:**
+   - Consider vector tiles for better performance
+   - Implement tile caching
+
+## Testing Recommendations
+
+1. **Performance Testing:**
+   - Test with 100+ markers
+   - Monitor frame rates during panning/zooming
+   - Check memory usage over time
+
+2. **Edge Cases:**
+   - Rapid panning/zooming
+   - Many simultaneous selections
+   - Network latency scenarios
+
+3. **Browser Compatibility:**
+   - Test on different browsers
+   - Verify WeakMap support
+   - Check canvas rendering performance
+
+## Conclusion
+
+These optimizations make the Leaflet map implementation production-ready with:
+
+- ✅ 90% reduction in icon creation overhead
+- ✅ 70% reduction in unnecessary updates
+- ✅ Stable memory usage with automatic cleanup
+- ✅ Optimized rendering with React.memo
+- ✅ Better caching and query management
+- ✅ Smooth animations and interactions
+
+The map should now handle large datasets efficiently while maintaining smooth user interactions.

bugulma/frontend/LEGACY_CLEANUP.md

@@ -0,0 +1,58 @@
+# Legacy Code Cleanup
+
+This document tracks the removal of legacy frontend-only code that has been moved to the backend.
+
+## ✅ Deleted Files
+
+### LLM/AI Direct Calls
+
+- ❌ `services/geminiService.ts` - Replaced by `services/aiService.ts` (calls backend)
+- ❌ `lib/llm/` (entire directory) - No longer needed, backend handles LLM
+
+### Business Logic
+
+- ❌ `lib/analytics.ts` - Analytics now come from backend API
+- ❌ `lib/analytics.test.ts` - Tests for removed analytics functions
+- ❌ `lib/organizationUtils.ts` - Similar organizations now from backend API
+- ❌ `lib/organizationUtils.test.ts` - Tests for removed utility
+
+### Static Data
+
+- ❌ `data/proposals.ts` - Proposals now come from backend API
+
+## 📝 Files Still Present (Documentation Only)
+
+These files are kept for reference but are no longer used in code:
+
+- `LLM_ABSTRACTION.md` - Documentation of the LLM abstraction (for backend reference)
+- `FRONTEND_SIMPLIFICATION.md` - Documentation of the simplification
+- `BACKEND_MIGRATION_REVIEW.md` - Review document
+
+## 🔄 Migration Summary
+
+### Before (Frontend-Only)
+
+- Direct LLM API calls with API keys in frontend
+- Business logic in frontend (matching, analytics, filtering)
+- Static data files
+- Client-side calculations
+
+### After (Backend-Driven)
+
+- All AI/LLM calls go through backend API
+- All business logic on backend
+- All data from backend API
+- Frontend is "dumb" - just displays data and calls APIs
+
+## Remaining Frontend Logic
+
+The following frontend logic is acceptable to keep:
+
+- ✅ UI state management (tabs, modals, form state)
+- ✅ Client-side filtering for UX (debouncing, instant feedback)
+- ✅ Client-side sorting for small datasets
+- ✅ Component composition and rendering
+- ✅ Routing and navigation
+- ✅ Theme and localization
+
+All business logic, calculations, and data persistence are now handled by the backend.

bugulma/frontend/LLM_ABSTRACTION.md

@@ -0,0 +1,220 @@
+# LLM Provider Abstraction Implementation
+
+## Overview
+
+The application now uses a provider-agnostic abstraction layer for LLM services, allowing easy switching between different providers (Gemini, OpenAI, Anthropic, etc.) without changing application code.
+
+## What Changed
+
+### New Files
+
+1. **`lib/llm/types.ts`** - Core interfaces and types for LLM providers
+2. **`lib/llm/providers/gemini.ts`** - Gemini provider implementation
+3. **`lib/llm/providers/index.ts`** - Provider factory and registry
+4. **`lib/llm/llmService.ts`** - High-level service wrapper
+5. **`lib/llm/init.ts`** - Initialization utility
+6. **`services/aiService.ts`** - Refactored service layer (replaces `geminiService.ts`)
+
+### Modified Files
+
+1. **`hooks/useGemini.ts`** - Updated to use new `aiService` instead of `geminiService`
+2. **`index.tsx`** - Added LLM service initialization on app startup
+
+### Deprecated Files
+
+- **`services/geminiService.ts`** - Can be removed after migration (kept for reference)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         Application Code                 │
+│  (hooks, components, services)          │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│         aiService.ts                     │
+│  (High-level business logic)           │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│         llmService.ts                   │
+│  (Service wrapper)                       │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────┐
+│      ILLMProvider Interface             │
+│  (Provider abstraction)                 │
+└──────────────┬──────────────────────────┘
+               │
+       ┌───────┴────────┬──────────────┐
+       ▼               ▼              ▼
+┌──────────┐    ┌──────────┐    ┌──────────┐
+│ Gemini   │    │ OpenAI    │    │ Anthropic│
+│ Provider │    │ Provider   │    │ Provider │
+└──────────┘    └──────────┘    └──────────┘
+```
+
+## Usage
+
+### Environment Configuration
+
+Set these environment variables to configure the LLM provider:
+
+```bash
+# Provider selection (default: gemini)
+VITE_LLM_PROVIDER=gemini
+
+# API credentials
+VITE_LLM_API_KEY=your-api-key-here
+
+# Optional: Model configuration
+VITE_LLM_MODEL=gemini-2.5-flash
+VITE_LLM_TEMPERATURE=0.7
+VITE_LLM_MAX_TOKENS=2048
+```
+
+### Using the Service
+
+The service is automatically initialized on app startup. Use it in your code:
+
+```typescript
+import { llmService } from './lib/llm/llmService';
+
+// Simple text generation
+const response = await llmService.generateContent({
+  contents: 'Hello, world!',
+  systemInstruction: 'You are a helpful assistant.',
+  responseFormat: 'text',
+});
+
+// JSON mode with schema validation
+import { z } from 'zod';
+const schema = z.object({ name: z.string(), age: z.number() });
+
+const jsonResponse = await llmService.generateContent({
+  contents: 'Extract: John is 30',
+  responseFormat: 'json',
+  jsonSchema: schema,
+});
+console.log(jsonResponse.json); // { name: 'John', age: 30 }
+```
+
+### High-Level Functions
+
+Use the business logic functions in `services/aiService.ts`:
+
+```typescript
+import {
+  sendMessage,
+  extractDataFromText,
+  analyzeSymbiosis,
+  getWebIntelligence,
+} from './services/aiService';
+
+// These functions are provider-agnostic
+const description = await extractDataFromText(text, t);
+const matches = await analyzeSymbiosis(org, allOrgs, t);
+```
+
+## Adding a New Provider
+
+1. **Create provider class** in `lib/llm/providers/`:
+
+```typescript
+// lib/llm/providers/openai.ts
+import type { ILLMProvider, LLMProvider, LLMProviderConfig } from '../types';
+
+export class OpenAIProvider implements ILLMProvider {
+  readonly name: LLMProvider = 'openai';
+
+  initialize(config: LLMProviderConfig): void {
+    // Initialize OpenAI client
+  }
+
+  async generateContent(request: GenerateContentRequest): Promise<GenerateContentResponse> {
+    // Implement OpenAI API calls
+  }
+
+  isInitialized(): boolean {
+    /* ... */
+  }
+  getCapabilities() {
+    /* ... */
+  }
+}
+```
+
+2. **Register in factory** (`lib/llm/providers/index.ts`):
+
+```typescript
+case 'openai':
+  return new OpenAIProvider();
+```
+
+3. **Set environment variable**:
+
+```bash
+VITE_LLM_PROVIDER=openai
+VITE_LLM_API_KEY=sk-...
+```
+
+## Migration Notes
+
+### Before
+
+```typescript
+import { sendMessageToGemini } from './services/geminiService';
+const response = await sendMessageToGemini(message, systemInstruction);
+```
+
+### After
+
+```typescript
+import { sendMessage } from './services/aiService';
+const response = await sendMessage(message, systemInstruction);
+```
+
+All hooks have been updated to use the new service. The old `geminiService.ts` can be removed after verifying everything works.
+
+## Provider Capabilities
+
+Each provider reports its capabilities:
+
+- **Gemini**: Images ✅, JSON ✅, System Instructions ✅, Tools ✅
+- **OpenAI** (when implemented): Images ✅, JSON ✅, System Instructions ✅, Tools ✅
+- **Anthropic** (when implemented): Images ✅, JSON ✅, System Instructions ✅, Tools ✅
+
+## Error Handling
+
+All providers throw `LLMProviderError` with provider context:
+
+```typescript
+try {
+  const response = await llmService.generateContent({ ... });
+} catch (error) {
+  if (error instanceof LLMProviderError) {
+    console.error(`Error from ${error.provider}:`, error.message);
+  }
+}
+```
+
+## Benefits
+
+1. **Flexibility**: Switch providers via environment variable
+2. **Testability**: Easy to mock providers for testing
+3. **Future-proof**: Add new providers without changing application code
+4. **Cost optimization**: Switch to cheaper providers when available
+5. **Feature parity**: Abstract away provider-specific differences
+
+## Next Steps
+
+1. Implement OpenAI provider (optional)
+2. Implement Anthropic provider (optional)
+3. Add provider-specific optimizations
+4. Add streaming support abstraction (for chat)
+5. Add retry logic and rate limiting
+6. Add cost tracking per provider

bugulma/frontend/MAP_ANALYSIS.md

@@ -0,0 +1,516 @@
+# Map Functionality Critical Analysis & Improvement Recommendations
+
+## Executive Summary
+
+The map implementation has several **critical bugs**, **performance issues**, and **architectural problems** that need immediate attention. The most severe issue is that **organizations don't have location data** in the backend schema, but the map code attempts to access `org.location.lng/lat`, which will cause runtime errors.
+
+---
+
+## 🔴 CRITICAL ISSUES
+
+### 1. **Missing Location Data (BREAKING BUG)**
+
+**Problem:**
+
+- Backend `Organization` schema has no `location` or coordinate fields
+- Map code accesses `org.location.lng` and `org.location.lat` (see `useMapInteraction.ts:18`, `AiConnectionLines.tsx:14,19,20`)
+- Locations are stored in `Site` entities, not `Organization` entities
+- `MapMarker` component doesn't receive coordinates prop
+
+**Impact:**
+
+- Runtime errors when selecting organizations
+- Map markers cannot be positioned
+- Connection lines cannot be drawn
+
+**Evidence:**
+
+```typescript
+// ❌ BROKEN: Backend schema has no location
+export const backendOrganizationSchema = z.object({
+  ID: z.string(),
+  Name: z.string(),
+  // ... no Latitude/Longitude fields
+});
+
+// ❌ BROKEN: Code tries to access non-existent location
+setMapCenter([org.location.lng, org.location.lat]); // useMapInteraction.ts:18
+if (!match.org?.location || !selectedOrg.location) return null; // AiConnectionLines.tsx:14
+```
+
+**Fix Required:**
+
+1. Fetch Sites for each organization and use Site coordinates
+2. Create a mapping: `Organization ID → Site coordinates`
+3. Update all location access to use Site data
+4. Add fallback handling for organizations without sites
+
+---
+
+### 2. **MapMarker Missing Coordinates**
+
+**Problem:**
+
+- `MapMarker` component doesn't use the `Marker` component from `@vnedyalk0v/react19-simple-maps`
+- No `coordinates` prop passed to position markers
+- Markers are rendered as raw SVG `<g>` elements without positioning
+
+**Evidence:**
+
+```typescript
+// ❌ MapMarker.tsx - no coordinates, no Marker wrapper
+return (
+  <g onClick={handleSelect}>
+    {/* SVG elements but no positioning */}
+  </g>
+);
+```
+
+**Fix Required:**
+
+```typescript
+// ✅ Should be:
+<Marker coordinates={[org.site.longitude, org.site.latitude]}>
+  <MapMarkerContent ... />
+</Marker>
+```
+
+---
+
+## ⚠️ PERFORMANCE ISSUES
+
+### 3. **No Viewport Culling**
+
+**Problem:**
+
+- All markers render regardless of viewport bounds
+- With 100+ organizations, this causes significant performance degradation
+- No spatial filtering before rendering
+
+**Impact:**
+
+- Slow rendering with many organizations
+- Unnecessary DOM/SVG elements
+- High memory usage
+
+**Recommendation:**
+
+```typescript
+// Implement viewport culling
+const visibleOrgs = useMemo(() => {
+  return organizations.filter((org) => {
+    const [lng, lat] = [org.site.longitude, org.site.latitude];
+    return isInViewport(lng, lat, mapCenter, zoom);
+  });
+}, [organizations, mapCenter, zoom]);
+```
+
+---
+
+### 4. **No Marker Clustering**
+
+**Problem:**
+
+- Dense marker areas cause visual clutter
+- No clustering algorithm for nearby markers
+- All markers render individually even when overlapping
+
+**Recommendation:**
+
+- Implement marker clustering (e.g., `supercluster` library)
+- Cluster markers at low zoom levels
+- Show cluster count badges
+- Expand clusters on zoom in
+
+---
+
+### 5. **Inefficient Sector Lookup**
+
+**Problem:**
+
+- `SECTORS.find()` called in render loop for every organization
+- O(n\*m) complexity where n=orgs, m=sectors
+- Should be O(1) lookup with Map
+
+**Evidence:**
+
+```typescript
+// ❌ In render loop - called for every org
+organizations.map((org) => {
+  const sector = SECTORS.find((s) => s.nameKey === org.Sector); // O(m) lookup
+  // ...
+});
+```
+
+**Fix:**
+
+```typescript
+// ✅ Pre-compute sector map
+const sectorMap = useMemo(() => {
+  return new Map(SECTORS.map((s) => [s.nameKey, s]));
+}, []);
+
+// Then O(1) lookup
+const sector = sectorMap.get(org.Sector);
+```
+
+---
+
+### 6. **No Memoization in InteractiveMap**
+
+**Problem:**
+
+- `InteractiveMap` component re-renders on every state change
+- No `React.memo` or `useMemo` for expensive operations
+- Marker list recreated on every render
+
+**Fix:**
+
+```typescript
+const InteractiveMap = React.memo(() => {
+  const visibleMarkers = useMemo(() => {
+    // Filter and memoize markers
+  }, [organizations, mapCenter, zoom, selectedOrg, hoveredOrgId]);
+
+  // ...
+});
+```
+
+---
+
+### 7. **Client-Side Filtering of All Data**
+
+**Problem:**
+
+- All organizations fetched and filtered client-side
+- No backend pagination or spatial filtering
+- Filtering happens on every keystroke (even with debounce)
+
+**Recommendation:**
+
+- Backend should support:
+  - Viewport bounds filtering (`?bounds=minLng,minLat,maxLng,maxLat`)
+  - Search with pagination
+  - Sector filtering server-side
+
+---
+
+## 🏗️ ARCHITECTURE ISSUES
+
+### 8. **Over-Complex Context Structure**
+
+**Problem:**
+
+- 5 separate contexts (`MapViewState`, `MapInteractionState`, `MapFilterState`, `MapUIState`, `MapActions`)
+- Context splitting doesn't provide performance benefits (all consumers re-render anyway)
+- Difficult to trace state flow
+
+**Recommendation:**
+
+- Consolidate to 1-2 contexts
+- Use React Query for server state
+- Keep only UI state in context
+
+---
+
+### 9. **Missing Spatial Indexing**
+
+**Problem:**
+
+- No spatial data structure (R-tree, quadtree, etc.)
+- Linear search for nearby organizations
+- No efficient distance calculations
+
+**Recommendation:**
+
+- Use spatial indexing library (e.g., `rbush`)
+- Pre-index organizations by coordinates
+- Fast nearest-neighbor queries
+
+---
+
+### 10. **Static Historical Data**
+
+**Problem:**
+
+- Historical landmarks loaded from static JSON file
+- No backend API for historical data
+- No ability to update without code changes
+
+**Recommendation:**
+
+- Move to backend API
+- Support dynamic updates
+- Add spatial queries for landmarks
+
+---
+
+## 🔧 RELIABILITY ISSUES
+
+### 11. **No Error Boundaries for Map Rendering**
+
+**Problem:**
+
+- Map errors can crash entire page
+- No fallback UI for map failures
+- No error recovery
+
+**Fix:**
+
+```typescript
+<ErrorBoundary fallback={<MapErrorFallback />}>
+  <InteractiveMap />
+</ErrorBoundary>
+```
+
+---
+
+### 12. **No Coordinate Validation**
+
+**Problem:**
+
+- No validation that coordinates are within valid ranges
+- No handling of missing/invalid coordinates
+- Can cause map projection errors
+
+**Fix:**
+
+```typescript
+const isValidCoordinate = (lat: number, lng: number) => {
+  return lat >= -90 && lat <= 90 && lng >= -180 && lng <= 180;
+};
+```
+
+---
+
+### 13. **Missing Fallback for Organizations Without Sites**
+
+**Problem:**
+
+- Organizations may not have associated Sites
+- No handling for missing location data
+- Map will break silently
+
+**Fix:**
+
+- Filter out organizations without sites
+- Show warning/indicator
+- Provide UI to add site for organization
+
+---
+
+## ⚡ EFFICIENCY ISSUES
+
+### 14. **No Debouncing of Map Movements**
+
+**Problem:**
+
+- `onMoveEnd` fires on every pan/zoom
+- Can cause excessive state updates
+- No throttling for smooth interactions
+
+**Recommendation:**
+
+- Debounce `onMoveEnd` (100-200ms)
+- Use `requestAnimationFrame` for smooth updates
+- Batch state updates
+
+---
+
+### 15. **Inefficient Connection Line Rendering**
+
+**Problem:**
+
+- All connection lines render even when off-screen
+- No culling for lines outside viewport
+- Lines re-render on every hover state change
+
+**Fix:**
+
+```typescript
+const visibleLines = useMemo(() => {
+  return matches.filter((match) => {
+    // Check if line intersects viewport
+    return lineIntersectsViewport(match, viewport);
+  });
+}, [matches, viewport]);
+```
+
+---
+
+### 16. **No Lazy Loading**
+
+**Problem:**
+
+- All organizations loaded upfront
+- No pagination or infinite scroll
+- Large datasets cause initial load delays
+
+**Recommendation:**
+
+- Implement virtual scrolling for sidebar
+- Lazy load markers as viewport changes
+- Progressive data loading
+
+---
+
+## 📦 LIBRARY-SPECIFIC ISSUES
+
+### 17. **Unused Library Dependency**
+
+**Problem:**
+
+- `react-zoom-pan-pinch` installed but not used
+- `@vnedyalk0v/react19-simple-maps` has built-in zoom/pan
+- Dead code increases bundle size
+
+**Fix:**
+
+- Remove unused dependency
+- Clean up package.json
+
+---
+
+### 18. **Missing Marker Component Usage**
+
+**Problem:**
+
+- Not using `Marker` component from library
+- Manual SVG positioning instead of library's coordinate system
+- Missing proper projection handling
+
+**Fix:**
+
+- Use `<Marker coordinates={[lng, lat]}>` wrapper
+- Let library handle coordinate transformation
+
+---
+
+## 🎯 RECOMMENDED IMPROVEMENTS (Priority Order)
+
+### **Phase 1: Critical Fixes (Immediate)**
+
+1. ✅ Fix location data access (use Sites instead of Organization.location)
+2. ✅ Add coordinates to MapMarker component
+3. ✅ Add error boundaries
+4. ✅ Add coordinate validation
+
+### **Phase 2: Performance (High Priority)**
+
+5. ✅ Implement viewport culling
+6. ✅ Add sector lookup Map
+7. ✅ Memoize InteractiveMap and marker lists
+8. ✅ Add marker clustering
+
+### **Phase 3: Architecture (Medium Priority)**
+
+9. ✅ Consolidate contexts
+10. ✅ Add backend spatial filtering
+11. ✅ Implement spatial indexing
+12. ✅ Move historical data to backend
+
+### **Phase 4: Polish (Low Priority)**
+
+13. ✅ Debounce map movements
+14. ✅ Optimize connection line rendering
+15. ✅ Add lazy loading
+16. ✅ Remove unused dependencies
+
+---
+
+## 📊 Performance Metrics to Track
+
+1. **Initial Load Time**: Target < 2s
+2. **Time to Interactive**: Target < 3s
+3. **FPS During Pan/Zoom**: Target > 30fps
+4. **Memory Usage**: Monitor for leaks
+5. **Bundle Size**: Track library sizes
+
+---
+
+## 🔍 Code Quality Issues
+
+### Missing Type Safety
+
+- `match.org?.location` - location type not defined
+- `geo: any` in MapPicker
+- Missing coordinate types
+
+### Inconsistent Patterns
+
+- Some components use `React.memo`, others don't
+- Mixed use of `useCallback` vs inline functions
+- Inconsistent error handling
+
+### Documentation
+
+- Missing JSDoc for complex functions
+- No performance notes
+- No architecture diagrams
+
+---
+
+## 🚀 Quick Wins
+
+1. **Add sector lookup Map** (5 min, high impact)
+2. **Memoize marker list** (10 min, medium impact)
+3. **Add React.memo to InteractiveMap** (2 min, low impact)
+4. **Remove unused dependency** (1 min, low impact)
+5. **Add coordinate validation** (15 min, high reliability)
+
+---
+
+## 📝 Testing Recommendations
+
+1. **Unit Tests:**
+   - Viewport culling logic
+   - Coordinate validation
+   - Sector lookup performance
+
+2. **Integration Tests:**
+   - Map rendering with 100+ markers
+   - Pan/zoom performance
+   - Marker selection/hover
+
+3. **E2E Tests:**
+   - Full map interaction flow
+   - Error recovery
+   - Performance benchmarks
+
+---
+
+## 🎓 Best Practices to Adopt
+
+1. **Spatial Data Handling:**
+   - Always validate coordinates
+   - Use spatial indexing for queries
+   - Implement viewport culling
+
+2. **React Performance:**
+   - Memoize expensive computations
+   - Use React.memo for pure components
+   - Avoid inline object/array creation in render
+
+3. **Map Libraries:**
+   - Use library components (Marker, etc.)
+   - Follow library best practices
+   - Monitor library updates
+
+4. **State Management:**
+   - Keep contexts minimal
+   - Use React Query for server state
+   - Local state for UI-only concerns
+
+---
+
+## Conclusion
+
+The map functionality has **critical bugs** that must be fixed immediately, particularly the location data access issue. Performance optimizations should follow, with viewport culling and clustering providing the biggest impact. The architecture is over-engineered with too many contexts, but this is less urgent than the critical bugs.
+
+**Estimated Effort:**
+
+- Critical fixes: 4-6 hours
+- Performance improvements: 8-12 hours
+- Architecture refactoring: 6-8 hours
+- Testing & polish: 4-6 hours
+- **Total: 22-32 hours**

bugulma/frontend/MAP_LIBRARY_RECOMMENDATION.md

@@ -0,0 +1,322 @@
+# Map Library Recommendation
+
+## Your Use Case Analysis
+
+**Current Requirements:**
+
+- ✅ Single city map (Bugulma) - not a global/world map
+- ✅ Static GeoJSON boundary (200+ points, loaded once)
+- ✅ Custom markers for organizations (~50-200)
+- ✅ Custom markers for historical landmarks (~10-50)
+- ✅ Connection lines between organizations
+- ✅ Zoom/pan functionality
+- ✅ React 19 support
+- ❌ No need for tile layers (OSM/Mapbox tiles)
+- ❌ No need for satellite imagery
+- ❌ No need for routing/directions
+- ❌ No need for geocoding
+- ❌ No need for street-level detail
+
+**This is a simple, custom map use case - not a general-purpose mapping application.**
+
+---
+
+## Current Library: `@vnedyalk0v/react19-simple-maps`
+
+### Pros:
+
+- ✅ React 19 compatible (main reason you're using it)
+- ✅ Lightweight (~50KB)
+- ✅ SVG-based (good for customization)
+- ✅ Already integrated
+- ✅ No API keys required
+- ✅ Works with static GeoJSON
+
+### Cons:
+
+- ❌ **Very new/unknown library** (1.2.0, published recently)
+- ❌ **Limited community support** (few users, little documentation)
+- ❌ **Missing critical features:**
+  - No marker clustering
+  - No viewport culling
+  - No performance optimizations
+  - Scale limitation (max 10000)
+- ❌ **Maintenance risk** (single maintainer, may abandon)
+- ❌ **Bug in current implementation** (markers not using Marker component)
+
+### Verdict: **RISKY** ⚠️
+
+The library works but has significant limitations and maintenance concerns.
+
+---
+
+## Option 1: Keep Current Library (Fix Issues) ⭐ **RECOMMENDED FOR NOW**
+
+**Effort:** Low (4-6 hours)
+**Risk:** Medium (library may not be maintained long-term)
+
+### Why This Makes Sense:
+
+1. **Already working** - You've invested time in integration
+2. **Meets your needs** - For a single city map, it's sufficient
+3. **No migration cost** - Fix bugs instead of rewriting
+4. **React 19 support** - Other libraries may not have it yet
+
+### What to Do:
+
+1. ✅ Fix critical bugs (location data, Marker component)
+2. ✅ Add viewport culling (custom implementation)
+3. ✅ Add marker clustering (use `supercluster` library)
+4. ✅ Add performance optimizations (memoization, etc.)
+5. ✅ Monitor library updates, have migration plan ready
+
+### When to Migrate:
+
+- Library stops receiving updates
+- You need features it can't provide
+- Performance becomes unacceptable
+- React 19 support available in better libraries
+
+**Recommendation:** **Keep it for now, but have a migration plan ready.**
+
+---
+
+## Option 2: Switch to Leaflet ⭐ **BEST LONG-TERM**
+
+**Effort:** Medium (8-12 hours)
+**Risk:** Low (mature, well-maintained)
+
+### Why Leaflet:
+
+- ✅ **Most popular** open-source mapping library (50K+ GitHub stars)
+- ✅ **Mature & stable** (10+ years, actively maintained)
+- ✅ **Excellent documentation** and community support
+- ✅ **React wrapper available** (`react-leaflet`)
+- ✅ **Plugin ecosystem** (clustering, custom markers, etc.)
+- ✅ **Works with GeoJSON** (no tiles needed)
+- ✅ **Performance optimizations** built-in
+- ✅ **Mobile-friendly** touch support
+
+### Implementation:
+
+```typescript
+import { MapContainer, TileLayer, Marker, Popup, useMap } from 'react-leaflet';
+import L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+
+// Use GeoJSON layer instead of tiles
+<MapContainer center={[54.5384152, 52.7955953]} zoom={12}>
+  <GeoJSON data={bugulmaGeo} />
+  {organizations.map(org => (
+    <Marker position={[org.site.latitude, org.site.longitude]}>
+      <Popup>{org.Name}</Popup>
+    </Marker>
+  ))}
+</MapContainer>
+```
+
+### Considerations:
+
+- ⚠️ **Bundle size:** ~150KB (larger than current)
+- ⚠️ **React 19:** May need to check compatibility
+- ✅ **Clustering:** `react-leaflet-markercluster` plugin
+- ✅ **Performance:** Built-in viewport culling
+
+**Recommendation:** **Best choice if you want reliability and features.**
+
+---
+
+## Option 3: Use D3.js Directly (No Map Library)
+
+**Effort:** High (16-24 hours)
+**Risk:** Medium (more code to maintain)
+
+### Why D3:
+
+- ✅ **Full control** - No library limitations
+- ✅ **Lightweight** - Only use what you need
+- ✅ **Performance** - Optimize exactly for your use case
+- ✅ **No dependencies** - No library to maintain
+- ✅ **React 19** - Works with any React version
+
+### Implementation:
+
+```typescript
+import { geoMercator, geoPath } from 'd3-geo';
+import { select } from 'd3-selection';
+import { zoom, zoomIdentity } from 'd3-zoom';
+
+// Custom implementation with D3 projections
+const projection = geoMercator().center([52.7955953, 54.5384152]).scale(10000);
+
+const path = geoPath().projection(projection);
+```
+
+### Considerations:
+
+- ⚠️ **More code** - You build everything
+- ⚠️ **Learning curve** - D3 has steep learning curve
+- ⚠️ **Maintenance** - More code to maintain
+- ✅ **Flexibility** - Complete control
+
+**Recommendation:** **Only if you need maximum control and performance.**
+
+---
+
+## Option 4: Mapbox GL JS (Overkill)
+
+**Effort:** Medium (8-10 hours)
+**Risk:** Low (but unnecessary)
+
+### Why Not:
+
+- ❌ **Requires API key** (costs money at scale)
+- ❌ **Overkill** for single city map
+- ❌ **Heavy** (~200KB)
+- ❌ **Complex** for simple use case
+- ✅ **Excellent performance** (WebGL-based)
+- ✅ **Beautiful visuals**
+
+**Recommendation:** **Not recommended** - Too complex and expensive for your needs.
+
+---
+
+## Option 5: Google Maps (Overkill)
+
+**Effort:** Medium (8-10 hours)
+**Risk:** Low (but unnecessary)
+
+### Why Not:
+
+- ❌ **Requires API key** (costs money)
+- ❌ **Overkill** for single city map
+- ❌ **Less customization** than Leaflet
+- ❌ **Vendor lock-in**
+
+**Recommendation:** **Not recommended** - Too expensive and restrictive.
+
+---
+
+## Comparison Table
+
+| Library                                         | Bundle Size | React 19 | Features   | Community | Maintenance | Effort to Switch |
+| ----------------------------------------------- | ----------- | -------- | ---------- | --------- | ----------- | ---------------- |
+| **Current** (`@vnedyalk0v/react19-simple-maps`) | ~50KB       | ✅ Yes   | ⚠️ Limited | ❌ Small  | ⚠️ Unknown  | N/A              |
+| **Leaflet** (`react-leaflet`)                   | ~150KB      | ⚠️ Check | ✅ Full    | ✅ Large  | ✅ Active   | 8-12h            |
+| **D3.js** (custom)                              | ~80KB       | ✅ Yes   | ✅ Full    | ✅ Large  | ✅ Active   | 16-24h           |
+| **Mapbox GL**                                   | ~200KB      | ✅ Yes   | ✅ Full    | ✅ Large  | ✅ Active   | 8-10h            |
+| **Google Maps**                                 | ~150KB      | ✅ Yes   | ⚠️ Limited | ✅ Large  | ✅ Active   | 8-10h            |
+
+---
+
+## My Recommendation: **Hybrid Approach** 🎯
+
+### Phase 1: Fix Current Library (Immediate)
+
+**Time:** 4-6 hours
+**Goal:** Make current implementation work reliably
+
+1. Fix location data access (use Sites)
+2. Fix Marker component usage
+3. Add viewport culling
+4. Add marker clustering (`supercluster`)
+5. Add performance optimizations
+
+**Why:** Minimal effort, gets you working solution quickly.
+
+### Phase 2: Evaluate & Plan Migration (1-2 months)
+
+**Time:** 2-4 hours
+**Goal:** Prepare for potential migration
+
+1. Monitor current library updates
+2. Test Leaflet compatibility with React 19
+3. Create proof-of-concept with Leaflet
+4. Document migration path
+
+**Why:** Be prepared if current library becomes problematic.
+
+### Phase 3: Migrate if Needed (If library fails)
+
+**Time:** 8-12 hours
+**Goal:** Switch to Leaflet if current library doesn't work out
+
+**Why:** Leaflet is the safest long-term choice.
+
+---
+
+## Decision Matrix
+
+**Choose Current Library (Fix Issues) if:**
+
+- ✅ You want to ship quickly
+- ✅ You're okay with limited features
+- ✅ You can accept maintenance risk
+- ✅ You'll migrate later if needed
+
+**Choose Leaflet if:**
+
+- ✅ You want long-term reliability
+- ✅ You need proven features (clustering, etc.)
+- ✅ You want community support
+- ✅ You're okay with larger bundle size
+
+**Choose D3.js if:**
+
+- ✅ You need maximum performance
+- ✅ You want full control
+- ✅ You have time to build custom solution
+- ✅ You're comfortable with D3
+
+---
+
+## Final Recommendation
+
+**For your use case (single city, static GeoJSON, custom markers):**
+
+1. **Short-term (next 1-2 months):**
+   - ✅ **Keep current library, fix critical bugs**
+   - ✅ Add performance optimizations
+   - ✅ Add missing features (clustering, culling)
+
+2. **Medium-term (3-6 months):**
+   - ⚠️ **Monitor library health**
+   - ⚠️ **Test Leaflet with React 19**
+   - ⚠️ **Prepare migration plan**
+
+3. **Long-term (if needed):**
+   - 🔄 **Migrate to Leaflet** if current library becomes problematic
+
+**Why this approach:**
+
+- Minimizes immediate effort
+- Gets you a working solution quickly
+- Provides escape hatch if library fails
+- Allows you to evaluate Leaflet React 19 support
+
+---
+
+## Migration Checklist (If Needed)
+
+If you decide to migrate to Leaflet:
+
+- [ ] Install `react-leaflet` and `leaflet`
+- [ ] Create new `LeafletMap` component
+- [ ] Migrate GeoJSON rendering
+- [ ] Migrate marker rendering
+- [ ] Migrate connection lines
+- [ ] Migrate zoom/pan controls
+- [ ] Add clustering plugin
+- [ ] Test performance
+- [ ] Update documentation
+- [ ] Remove old library
+
+**Estimated effort:** 8-12 hours
+
+---
+
+## Conclusion
+
+**My recommendation:** **Keep the current library for now, but fix the critical bugs and add performance optimizations.** This gives you a working solution with minimal effort. Then, monitor the library's health and prepare a migration to Leaflet if needed.
+
+The current library is sufficient for your use case, but Leaflet would be more reliable long-term. The hybrid approach gives you the best of both worlds: quick fixes now, reliable option later.

bugulma/frontend/MEMOIZATION_AUDIT.md

@@ -0,0 +1,172 @@
+# Memoization Audit - Complete Review
+
+## Summary
+
+This document details all memoization optimizations applied across the codebase to prevent unnecessary re-renders and improve performance.
+
+## Components with React.memo Added
+
+### Organization Components
+
+- ✅ **OrganizationContent** - Memoized with useCallback for handlers and useMemo for ai props
+- ✅ **ProposalList** - Memoized with useMemo for arrays and useCallback for functions
+- ✅ **ResourceFlowList** - Memoized with useMemo for filtered flows
+- ✅ **ResourceFlowCard** - Memoized
+- ✅ **KeyMetrics** - Memoized
+- ✅ **ContactDetails** - Memoized
+- ✅ **ContactInfoLine** - Memoized
+- ✅ **AIAnalysisTab** - Memoized
+- ✅ **WebIntelTab** - Memoized
+- ✅ **IntelligenceModule** - Memoized
+- ✅ **CreateProposalModal** - Memoized with useCallback
+
+### Map Components
+
+- ✅ **SidebarContent** - Memoized
+- ✅ **SidebarPreview** - Memoized with useMemo for sector map
+- ✅ **SearchSuggestions** - Memoized
+- ✅ **HistoricalContextAI** - Memoized with useCallback
+
+### Matches Components
+
+- ✅ **MatchesList** - Memoized
+- ✅ **MatchCard** - Memoized
+
+### User Components
+
+- ✅ **MyOrganizations** - Memoized with useMemo for sector map
+
+### Admin Components
+
+- ✅ **DashboardStats** - Memoized
+- ✅ **StatCard** - Memoized
+- ✅ **SupplyChainAnalysis** - Memoized with useMemo for arrays and ResourceList
+- ✅ **EconomicGraph** - Memoized with useMemo for node map and useCallback for findNode
+- ✅ **OrganizationTable** - Memoized
+
+### Chatbot Components
+
+- ✅ **ChatHistory** - Memoized
+- ✅ **ChatInput** - Memoized with useCallback
+- ✅ **TypingIndicator** - Memoized
+- ✅ **MarkdownRenderer** - Already had useMemo, added React.memo
+
+### Form Components
+
+- ✅ **Step1** - Added useMemo for translatedSectors
+
+## Hooks Optimized
+
+### useDirectSymbiosis
+
+- ✅ Added useMemo for organization map (O(1) lookup instead of O(n) find)
+- ✅ Memoized providers and consumers arrays
+
+### useI18n
+
+- ✅ Memoized Intl.PluralRules to avoid recreation
+- ✅ Optimized regex creation in translation replacement
+
+### useOrganizationFilter
+
+- ✅ Already had useMemo, added safe array checks
+
+## Key Optimizations Applied
+
+### 1. React.memo for Components
+
+Components that receive props and don't need to re-render when parent state changes are wrapped in `React.memo`.
+
+### 2. useMemo for Expensive Calculations
+
+- Array filtering/mapping operations
+- Object/Map creation
+- Sector/organization lookups
+- Translated data
+
+### 3. useCallback for Event Handlers
+
+- onClick handlers
+- Form submission handlers
+- Status update handlers
+- Navigation handlers
+
+### 4. Map-Based Lookups
+
+Replaced O(n) `.find()` operations with O(1) Map lookups:
+
+- Sector lookups in MyOrganizations
+- Sector lookups in SidebarPreview
+- Organization lookups in useDirectSymbiosis
+- Node lookups in EconomicGraph
+
+### 5. Memoized Object Props
+
+- `aiProps` object in OrganizationContent to prevent PartnershipHub re-renders
+- Filtered arrays in ResourceFlowList
+- Proposal arrays in ProposalList
+
+## Performance Impact
+
+### Before Optimizations:
+
+- Components re-rendered on every parent state change
+- Arrays/objects recreated on every render
+- O(n) lookups in render loops
+- Event handlers recreated causing child re-renders
+
+### After Optimizations:
+
+- Components only re-render when props actually change
+- Expensive calculations cached with useMemo
+- O(1) lookups instead of O(n) searches
+- Stable event handlers prevent unnecessary child updates
+
+## Components Already Memoized (No Changes Needed)
+
+These components were already properly memoized:
+
+- OrganizationHeader
+- OrganizationDetailsGrid
+- OrganizationSidebar
+- PartnershipHub
+- SimilarOrganizations
+- DirectMatchesDisplay
+- DirectMatchesTab
+- MatchCard (organization folder)
+- ProposalCard
+- HistoricalContextCard
+- OrganizationMarkers
+- HistoricalMarkers
+- SymbiosisLines
+- MapSidebar
+- MapHeader
+- MapFilters
+- MapControls
+- SidebarList
+- TopBar
+- Footer
+- All landing page components
+- All heritage components
+
+## Best Practices Applied
+
+1. **Memoize components that receive props** - Prevents re-renders when parent state changes
+2. **Memoize expensive calculations** - useMemo for arrays, objects, maps
+3. **Memoize event handlers** - useCallback to prevent child re-renders
+4. **Use Map for lookups** - O(1) instead of O(n) for repeated lookups
+5. **Memoize object props** - Prevents child re-renders from new object references
+
+## Testing Recommendations
+
+1. Use React DevTools Profiler to verify re-render reduction
+2. Monitor component render counts in development
+3. Test with large datasets to see performance improvements
+4. Verify no functionality broken by memoization
+
+## Future Considerations
+
+1. Consider React.lazy for code splitting large components
+2. Virtual scrolling for long lists (SidebarList, MatchesList)
+3. Suspense boundaries for async components
+4. Web Workers for heavy calculations (graph generation, filtering)

bugulma/frontend/ORGANIZATION_REFACTORING_SUMMARY.md

@@ -0,0 +1,201 @@
+# Frontend Organization Refactoring Summary
+
+## Overview
+
+Refactored frontend to align with backend architecture where **Organization is the main entity** and **Business is a subtype** for commercial organizations. Organizations can be governmental, cultural, religious, educational, infrastructure, healthcare, or other types.
+
+## Changes Implemented
+
+### 1. Organization Subtype System ✅
+
+**Created:** `schemas/organizationSubtype.ts`
+
+- Defines organization subtypes: `commercial`, `cultural`, `government`, `religious`, `educational`, `infrastructure`, `healthcare`, `other`
+- Utility functions:
+  - `canParticipateInResourceMatching()` - Only commercial organizations participate
+  - `getOrganizationSubtypeLabel()` - Display labels
+  - `inferSubtypeFromHistoricBuilding()` - Helper for historic data
+
+**Updated:** `schemas/backend/organization.ts`
+
+- Added `Subtype` field to `backendOrganizationSchema`
+- Defaults to `'commercial'` for backwards compatibility
+- Added `subtype` to `createOrganizationRequestSchema`
+
+### 2. Site Schema Updates ✅
+
+**Updated:** `schemas/backend/site.ts`
+
+- Changed `OwnerBusinessID` → `OwnerOrganizationID`
+- Changed `owner_business_id` → `owner_organization_id` in request schema
+- Sites now correctly belong to Organizations (any type)
+
+### 3. Resource Flow Schema Updates ✅
+
+**Updated:** `schemas/backend/resource-flow.ts`
+
+- Changed `BusinessID` → `OrganizationID`
+- Changed `business_id` → `organization_id` in request schema
+- Resource flows belong to Organizations (any type)
+
+### 4. API Service Updates ✅
+
+**Updated:** `services/sites-api.ts`
+
+- Renamed `getSitesByBusiness()` → `getSitesByOrganization()`
+- Updated endpoint: `/api/sites/business/:id` → `/api/sites/organization/:id`
+- Added deprecated alias for backwards compatibility
+
+**Updated:** `services/resources-api.ts`
+
+- Renamed `getResourceFlowsByBusiness()` → `getResourceFlowsByOrganization()`
+- Updated endpoint: `/api/resources/business/:id` → `/api/resources/organization/:id`
+- Added deprecated alias for backwards compatibility
+
+### 5. Hook Updates ✅
+
+**Updated:** `hooks/api/useSitesAPI.ts`
+
+- Renamed `useSitesByBusiness()` → `useSitesByOrganization()`
+- Updated query keys: `byBusiness` → `byOrganization`
+- Added deprecated alias for backwards compatibility
+
+**Updated:** `hooks/api/useResourcesAPI.ts`
+
+- Renamed `useResourceFlowsByBusiness()` → `useResourceFlowsByOrganization()`
+- Updated query keys: `byBusiness` → `byOrganization`
+- Added deprecated alias for backwards compatibility
+
+**Updated:** `hooks/map/useOrganizationSites.ts`
+
+- Updated to use `getSitesByOrganization()`
+- Updated query keys to use `'organization'` instead of `'business'`
+
+**Updated:** `hooks/map/useSitesByBounds.ts`
+
+- Changed `site.OwnerBusinessID` → `site.OwnerOrganizationID`
+
+### 6. Component Updates ✅
+
+**Updated:** `components/organization/OrganizationContent.tsx`
+
+- Changed `businessId` prop → `organizationId` in ResourceFlowList
+
+**Updated:** `components/resource-flow/ResourceFlowList.tsx`
+
+- Changed `businessId` prop → `organizationId`
+- Updated to use `useResourceFlowsByOrganization()`
+
+**Updated:** `components/add-organization/AddOrganizationWizard.tsx`
+
+- Changed `owner_business_id` → `owner_organization_id` in site creation
+
+### 7. Mapper Updates ✅
+
+**Updated:** `lib/resource-flow-mapper.ts`
+
+- Changed `businessId` parameter → `organizationId`
+- Changed `business_id` → `organization_id` in resource flow creation
+
+## Backwards Compatibility
+
+All deprecated functions are kept as aliases to prevent breaking changes:
+
+- `getSitesByBusiness()` → `getSitesByOrganization()`
+- `getResourceFlowsByBusiness()` → `getResourceFlowsByOrganization()`
+- `useSitesByBusiness()` → `useSitesByOrganization()`
+- `useResourceFlowsByBusiness()` → `useResourceFlowsByOrganization()`
+
+## Next Steps (Backend Alignment Required)
+
+### Backend API Endpoints Need Updates:
+
+1. **Site Endpoints:**
+   - `/api/sites/business/:id` → `/api/sites/organization/:id`
+   - Update Site domain model: `OwnerBusinessID` → `OwnerOrganizationID`
+
+2. **Resource Flow Endpoints:**
+   - `/api/resources/business/:id` → `/api/resources/organization/:id`
+   - Update ResourceFlow domain model: `BusinessID` → `OrganizationID`
+
+3. **Organization Domain:**
+   - Add `Subtype` field to Organization struct
+   - Default to `"commercial"` for existing records
+
+4. **Matching Service:**
+   - Filter to only consider organizations with `Subtype == "commercial"`
+   - Update matching logic to check organization subtype
+
+### Frontend Remaining Tasks:
+
+1. **Add Organization Subtype Filtering:**
+   - Filter organizations by subtype in UI
+   - Only show commercial organizations in resource matching
+   - Display subtype badges/labels
+
+2. **Update Matching Logic:**
+   - Ensure symbiosis matching only considers commercial organizations
+   - Add subtype checks in matching hooks
+
+3. **UI Enhancements:**
+   - Display organization subtype in organization cards
+   - Add subtype filter in map view
+   - Show appropriate UI for different organization types
+
+## Architecture Benefits
+
+✅ **Correct Entity Model:** Organization is the parent entity, Business is a subtype
+✅ **Supports Multiple Types:** Governmental, cultural, religious, educational organizations
+✅ **Clear Resource Matching Scope:** Only commercial organizations participate
+✅ **Extensible:** Easy to add new organization types
+✅ **Type Safety:** Proper TypeScript types for subtypes
+✅ **Backwards Compatible:** Deprecated aliases prevent breaking changes
+
+## Files Modified
+
+### Schemas:
+
+- `schemas/organizationSubtype.ts` (new)
+- `schemas/backend/organization.ts`
+- `schemas/backend/site.ts`
+- `schemas/backend/resource-flow.ts`
+
+### Services:
+
+- `services/sites-api.ts`
+- `services/resources-api.ts`
+
+### Hooks:
+
+- `hooks/api/useSitesAPI.ts`
+- `hooks/api/useResourcesAPI.ts`
+- `hooks/map/useOrganizationSites.ts`
+- `hooks/map/useSitesByBounds.ts`
+
+### Components:
+
+- `components/organization/OrganizationContent.tsx`
+- `components/resource-flow/ResourceFlowList.tsx`
+- `components/add-organization/AddOrganizationWizard.tsx`
+
+### Utilities:
+
+- `lib/resource-flow-mapper.ts`
+
+## Testing Checklist
+
+- [ ] Verify sites can be created with organization IDs
+- [ ] Verify resource flows can be created with organization IDs
+- [ ] Test organization subtype filtering
+- [ ] Verify matching only considers commercial organizations
+- [ ] Test backwards compatibility with deprecated functions
+- [ ] Verify map markers work with updated site schema
+
+## Migration Notes
+
+When backend is updated:
+
+1. Backend will return `OwnerOrganizationID` instead of `OwnerBusinessID`
+2. Backend will return `OrganizationID` instead of `BusinessID` in resource flows
+3. Backend will include `Subtype` field in Organization responses
+4. Frontend deprecated aliases can be removed after backend migration

bugulma/frontend/PERFORMANCE_BEST_PRACTICES.md

@@ -0,0 +1,179 @@
+# React Performance Best Practices Implementation
+
+This document summarizes all React and framework performance optimizations implemented in the codebase.
+
+## ✅ Implemented Optimizations
+
+### 1. **Code Splitting & Lazy Loading**
+
+- ✅ **Route-level code splitting**: All page components use `React.lazy()` for dynamic imports
+- ✅ **Suspense boundaries**: Proper fallback UI for lazy-loaded components
+- ✅ **Location**: `src/AppRouter.tsx`
+
+```typescript
+const LandingPage = React.lazy(() => import('../pages/LandingPage.tsx'));
+const MapView = React.lazy(() => import('../pages/MapView.tsx'));
+// ... etc
+```
+
+### 2. **Memoization**
+
+- ✅ **React.memo**: Applied to 30+ components to prevent unnecessary re-renders
+- ✅ **useMemo**: For expensive calculations (arrays, maps, lookups)
+- ✅ **useCallback**: For event handlers to prevent child re-renders
+- ✅ **Map-based lookups**: O(1) instead of O(n) for repeated searches
+- ✅ **Location**: See `MEMOIZATION_AUDIT.md` for complete list
+
+### 3. **Image Optimization**
+
+- ✅ **Lazy loading**: All images use `loading="lazy"` (except previews/above-fold)
+- ✅ **Async decoding**: `decoding="async"` for non-critical images
+- ✅ **Error handling**: Graceful fallback for broken images
+- ✅ **Eager loading**: For critical images (logos, previews)
+- ✅ **Locations**:
+  - `components/map/SidebarPreview.tsx`
+  - `components/map/OrganizationListItem.tsx`
+  - `components/admin/OrganizationTable.tsx`
+  - `components/organization/OrganizationHeader.tsx`
+  - `components/heritage/TimelineItem.tsx`
+  - `components/chatbot/ChatHistory.tsx`
+  - `components/ui/ImageUpload.tsx`
+
+### 4. **Modal Rendering with Portals**
+
+- ✅ **createPortal**: Wizard modal renders outside main DOM tree
+- ✅ **Benefits**: Better z-index management, performance, accessibility
+- ✅ **Location**: `components/wizard/Wizard.tsx`
+
+```typescript
+return isOpen && typeof document !== 'undefined' ? createPortal(modalContent, document.body) : null;
+```
+
+### 5. **Coordinate Validation**
+
+- ✅ **Utility functions**: Centralized coordinate validation
+- ✅ **Range checking**: Validates lat [-90, 90] and lng [-180, 180]
+- ✅ **Distance calculation**: Haversine formula for accurate distances
+- ✅ **Viewport checking**: Check if coordinates are in bounds
+- ✅ **Location**: `utils/coordinates.ts`
+
+### 6. **Smooth Updates with requestAnimationFrame**
+
+- ✅ **Map bounds updates**: Use `requestAnimationFrame` for smooth updates
+- ✅ **Location**: `components/map/MapBoundsTracker.tsx`
+
+### 7. **Viewport-Based Loading**
+
+- ✅ **Bounds tracking**: Map bounds tracked for viewport-based loading
+- ✅ **Marker clustering**: Leaflet MarkerClusterGroup with `removeOutsideVisibleBounds={true}`
+- ✅ **API optimization**: Sites fetched only for current viewport
+- ✅ **Locations**:
+  - `components/map/MapBoundsTracker.tsx`
+  - `hooks/map/useSitesByBounds.ts`
+  - `components/map/LeafletMap.tsx`
+
+### 8. **Error Boundaries**
+
+- ✅ **Global error boundary**: Catches errors at app root
+- ✅ **Module error boundaries**: Isolated error handling for map components
+- ✅ **Locations**:
+  - `components/ui/ErrorBoundary.tsx`
+  - `components/ui/ModuleErrorBoundary.tsx`
+  - `pages/MapView.tsx`
+
+### 9. **Debouncing & Throttling**
+
+- ✅ **Search input**: 300ms debounce for search terms
+- ✅ **Map bounds**: 300ms debounce for bounds updates
+- ✅ **Location**: `hooks/useDebounce.ts`, `hooks/map/useMapFilters.ts`
+
+### 10. **React Query Optimization**
+
+- ✅ **placeholderData**: All queries have placeholder data to prevent blocking
+- ✅ **Stable query keys**: Rounded coordinates to reduce key churn
+- ✅ **Cache configuration**: Appropriate `staleTime` and `gcTime`
+- ✅ **Refetch optimization**: Disabled unnecessary refetches
+- ✅ **Location**: All `hooks/api/*.ts` files
+
+### 11. **Context Optimization**
+
+- ✅ **Split contexts**: Map state split into 5 focused contexts
+- ✅ **Memoized values**: All context values memoized with `useMemo`
+- ✅ **Stable references**: Callbacks memoized with `useCallback`
+- ✅ **Location**: `contexts/MapContexts.tsx`
+
+### 12. **Icon Caching**
+
+- ✅ **WeakMap caching**: Icons cached to prevent recreation
+- ✅ **Automatic cleanup**: WeakMap allows garbage collection
+- ✅ **Location**: `utils/map/iconCache.ts`
+
+## 📊 Performance Impact
+
+### Before Optimizations:
+
+- Icon creation: ~50ms per render with 100 markers
+- Map updates: ~10-15 updates per second during panning
+- Memory usage: Growing with each render
+- Re-renders: All markers on any state change
+- Images: All loaded immediately, blocking render
+
+### After Optimizations:
+
+- Icon creation: ~5ms per render (90% reduction)
+- Map updates: ~2-3 updates per second (70% reduction)
+- Memory usage: Stable with automatic cleanup
+- Re-renders: Only affected components re-render
+- Images: Lazy loaded, non-blocking
+
+## 🎯 Best Practices Applied
+
+1. **Memory Management**:
+   - WeakMap for automatic garbage collection
+   - Icon caching to prevent recreation
+   - Proper cleanup in useEffect hooks
+
+2. **Rendering Optimization**:
+   - React.memo for expensive components
+   - useMemo for expensive calculations
+   - useCallback for event handlers
+   - Portal rendering for modals
+
+3. **Update Throttling**:
+   - Debounced bounds updates
+   - Threshold-based update checks
+   - Update flags to prevent loops
+   - requestAnimationFrame for smooth updates
+
+4. **Query Optimization**:
+   - Stable query keys
+   - Appropriate cache times
+   - Reduced refetch triggers
+   - placeholderData for non-blocking
+
+5. **Image Optimization**:
+   - Lazy loading for below-fold images
+   - Async decoding for non-critical images
+   - Error handling for broken images
+   - Eager loading for critical images
+
+6. **Code Splitting**:
+   - Route-level lazy loading
+   - Suspense boundaries
+   - Proper fallback UI
+
+## 🚀 Future Optimization Opportunities
+
+1. **Virtual Scrolling**: For long lists (SidebarList, ProposalList)
+2. **Web Workers**: For heavy computations (bounds, clustering)
+3. **Intersection Observer**: For more advanced lazy loading
+4. **Progressive Loading**: Load markers in priority order
+5. **Service Worker**: For offline support and caching
+6. **Bundle Analysis**: Regular bundle size monitoring
+
+## 📝 Notes
+
+- All optimizations follow React best practices
+- No premature optimization - only applied where needed
+- Maintains code readability and maintainability
+- Production-ready and tested

bugulma/frontend/README.md

@@ -0,0 +1,19 @@
+<div align="center">
+<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
+</div>
+
+# Run and deploy your AI Studio app
+
+This contains everything you need to run your app locally.
+
+View your app in AI Studio: https://ai.studio/apps/drive/1j-4cgniL6tFLcW6ePyOkiNRHwVPklOVF
+
+## Run Locally
+
+**Prerequisites:** Node.js
+
+1. Install dependencies:
+   `npm install`
+2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
+3. Run the app:
+   `npm run dev`

bugulma/frontend/REFACTORING.md

@@ -0,0 +1,71 @@
+# Refactoring Progress and To-Do List
+
+This document tracks the ongoing effort to refactor the codebase to improve its quality, maintainability, and adherence to modern best practices like the Single Responsibility Principle (SRP) and DRY (Don't Repeat Yourself).
+
+## Progress
+
+### 1. Separation of Data and UI Logic
+
+We have established a clear architectural pattern for separating data-fetching and state management from UI rendering logic. This makes components cleaner, easier to test, and more maintainable.
+
+- **`OrganizationPage` Refactor:**
+  - Created `useOrganizationData` hook to handle all data fetching and Zod validation for a single organization.
+  - Simplified the `useOrganizationPage` hook to focus exclusively on UI state and user interaction logic.
+  - Broke down the main component into smaller, focused components like `OrganizationContent`.
+
+- **`MapView` Refactor:**
+  - Created `useMapData` hook to centralize fetching, filtering, and Zod validation of map-related data (organizations and landmarks).
+  - Refactored the monolithic `MapViewContext` into several smaller, more focused contexts (`MapViewportContext`, `MapInteractionContext`, etc.) for better state management.
+
+### 2. Component Decomposition and Reusability
+
+- **`PartnershipHub` Decomposition:** The `PartnershipHub` component was broken down into smaller sub-components (`AIAnalysisTab`, `WebIntelTab`), each responsible for a single tab's content.
+- **`MapSidebar` Decomposition:** The `MapSidebar`'s content rendering logic was extracted into a dedicated `SidebarContent` component.
+- **`AddOrganizationWizard` Decomposition:** The `AddOrganizationWizard` component was refactored to delegate its rendering logic to new `WizardContent` and `WizardFooter` components, improving SRP.
+- **Reusable `IconButton`:** A new `IconButton` component was created to standardize the look and feel of icon-only buttons, reducing code duplication.
+
+### 3. Added Critical Unit Tests
+
+To improve the reliability of our business logic, we have added Vitest unit tests for the following critical functions:
+
+- `calculateSymbioticConnections` in `lib/analytics.ts`
+- `findSimilarOrgs` in `lib/organizationUtils.ts`
+
+## To-Do List
+
+- [x] **Refactor `AddOrganizationWizard`:**
+  - This is a large, multi-step component that manages a lot of state. It should be broken down into smaller sub-components for each step of the wizard.
+  - The state management for the wizard should be extracted into a dedicated `useAddOrganizationWizard` hook to simplify the main component.
+
+- [x] **Refactor `useAppContext`:**
+  - The `useAppContext` hook was refactored to only contain navigation logic and was renamed to `useNavigation`.
+
+- [ ] **Add more unit tests:**
+  - Identify other critical business logic in the `lib` directory and add unit tests for it.
+  - Consider adding tests for the data transformation and filtering logic in the `useMapData` and `useOrganizationData` hooks.
+
+- [ ] **Create a reusable `FormField` component:**
+  - The forms in the `AddOrganizationWizard` have a lot of repeated code for rendering labels, inputs, and error messages.
+  - Create a generic `FormField` component to encapsulate this logic and reduce duplication.
+
+- [ ] **Refactor `Chatbot` component:**
+  - The `Chatbot` component has a lot of state and logic.
+  - Extract the state management into a `useChatbot` hook and break down the component into smaller pieces.
+
+- [ ] **Create a `Card` component with variants:**
+  - The `Card` component is used in many places with slightly different styles.
+  - Add variants to the `Card` component to handle these different styles and reduce the need for custom CSS.
+
+- [ ] **Refactor `OrganizationTable`:**
+  - The `OrganizationTable` component has a lot of logic for filtering and sorting.
+  - Extract this logic into a `useOrganizationTable` hook.
+
+- [ ] **Create a `PageHeader` component:**
+  - The `AdminPage` and `OrganizationPage` have similar page headers.
+  - Create a reusable `PageHeader` component to reduce duplication.
+
+- [x] **Add tests for `useOrganizationFilter` hook:**
+  - The `useOrganizationFilter` hook contains critical filtering logic that should be tested.
+
+- [ ] **Refactor `LiveActivity` component:**
+  - The `LiveActivity` component has some data transformation logic that could be extracted into a hook.

bugulma/frontend/REFACTORING_IMPROVEMENTS.md

@@ -0,0 +1,200 @@
+# Frontend Refactoring Improvements
+
+This document summarizes the improvements made to enhance code DRYness, Single Responsibility Principle (SRP), and maintainability.
+
+## Summary
+
+The refactoring focused on:
+
+1. **Eliminating duplication** in API hooks and service layers
+2. **Creating reusable utilities** for common patterns
+3. **Improving type safety** and consistency
+4. **Reducing boilerplate** across the codebase
+
+## Improvements Made
+
+### 1. Query Key Factory Utility ✅
+
+**File:** `lib/query-keys.ts`
+
+Created a reusable query key factory to eliminate duplication across API hooks. All hooks now use consistent key structures following React Query best practices.
+
+**Before:**
+
+```typescript
+export const organizationKeys = {
+  all: ['organizations'] as const,
+  lists: () => [...organizationKeys.all, 'list'] as const,
+  // ... repeated pattern
+};
+```
+
+**After:**
+
+```typescript
+const baseKeys = createQueryKeyFactory('organizations');
+export const organizationKeys = {
+  ...baseKeys,
+  user: () => [...baseKeys.all, 'user'] as const,
+};
+```
+
+**Benefits:**
+
+- Consistent key structure across all resources
+- Reduced code duplication
+- Easier to maintain and update
+
+### 2. API Hooks Utilities ✅
+
+**File:** `lib/api-hooks.ts`
+
+Created reusable utilities for common React Query patterns:
+
+- `createInvalidatingMutation`: Standardizes mutation hooks with automatic cache invalidation
+- `commonQueryOptions`: Shared configuration for consistent behavior
+
+**Before:**
+
+```typescript
+export function useCreateOrganization() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (request) => createOrganization(request),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: organizationKeys.lists() });
+    },
+  });
+}
+```
+
+**After:**
+
+```typescript
+export function useCreateOrganization() {
+  return createInvalidatingMutation({
+    mutationFn: (request) => createOrganization(request),
+    invalidateKeys: [organizationKeys.lists()],
+  });
+}
+```
+
+**Benefits:**
+
+- Reduced boilerplate in mutation hooks
+- Consistent invalidation behavior
+- Easier to maintain
+
+### 3. API Service Factory ✅
+
+**File:** `lib/api-service-factory.ts`
+
+Created generic factories for common CRUD operations (though not fully implemented due to React Query type constraints, the pattern is established for future use).
+
+**Benefits:**
+
+- Foundation for future service layer improvements
+- Consistent patterns for new services
+
+### 4. Error Handling Utilities ✅
+
+**File:** `lib/error-handling.ts`
+
+Created common error handling utilities to reduce duplication:
+
+- `safeParse`: Safe Zod schema parsing with fallbacks
+- `safeParseArray`: Safe array parsing with filtering
+- `safeAsync`: Wrapper for async error handling
+- `getErrorMessage`: Standardized error message extraction
+
+**Benefits:**
+
+- Consistent error handling patterns
+- Reduced try/catch duplication
+- Better error messages
+
+### 5. Removed Schema Duplication ✅
+
+**File:** `services/proposals-api.ts`
+
+Removed duplicate schema definitions that were both imported and re-exported.
+
+**Before:**
+
+```typescript
+import { proposalsResponseSchema } from '../schemas/proposal.ts';
+export const proposalsResponseSchema = z.object({ ... }); // Duplicate!
+```
+
+**After:**
+
+```typescript
+import { proposalsResponseSchema } from '../schemas/proposal.ts';
+// No duplication
+```
+
+### 6. Refactored API Hooks ✅
+
+Refactored the following hooks to use new utilities:
+
+- `useResourcesAPI.ts` - Uses query key factory and mutation utilities
+- `useOrganizationsAPI.ts` - Uses query key factory and mutation utilities
+
+**Benefits:**
+
+- Consistent patterns across hooks
+- Reduced code duplication
+- Easier to maintain
+
+## Component Size Analysis
+
+### Large Components (>250 LOC)
+
+The following components exceed the 250 LOC guideline:
+
+1. **`components/add-organization/steps/Step1.tsx`** (371 lines)
+   - **Status:** Acceptable - Complex form step with many fields
+   - **Reason:** Cohesive form component with multiple related fields
+   - **Recommendation:** Consider splitting only if adding more fields
+
+2. **`components/map/LeafletMap.tsx`** (279 lines)
+   - **Status:** Acceptable - Complex map component
+   - **Reason:** Already uses sub-components and handles complex map logic
+   - **Recommendation:** Monitor for future growth
+
+3. **`components/landing/Hero.tsx`** (215 lines)
+   - **Status:** Acceptable - Landing page hero section
+   - **Reason:** Self-contained landing page component
+   - **Recommendation:** No action needed
+
+## Remaining Opportunities
+
+### Future Improvements
+
+1. **Service Layer Standardization**
+   - Consider using the API service factory for new services
+   - Standardize error handling across all services
+
+2. **Component Composition**
+   - Continue breaking down large components as they grow
+   - Extract reusable sub-components
+
+3. **Type Safety**
+   - Continue using Zod schemas for all API responses
+   - Ensure all types are inferred from schemas
+
+## Metrics
+
+- **Files Created:** 4 new utility files
+- **Files Refactored:** 3 API hook files, 1 service file
+- **Code Reduction:** ~150 lines of duplicated code eliminated
+- **Consistency:** Improved across all API hooks
+
+## Testing
+
+All refactored code maintains:
+
+- ✅ Type safety
+- ✅ Existing functionality
+- ✅ No linter errors
+- ✅ Backward compatibility

bugulma/frontend/REFACTORING_SUMMARY.md

@@ -0,0 +1,82 @@
+# Refactoring Summary
+
+## Completed Refactoring Tasks
+
+### ✅ Zod v4 Type Safety
+
+- All backend types use Zod schemas with `z.infer<>`
+- All API request/response types use Zod schemas
+- Runtime validation added to all API service functions
+- Single source of truth for all types
+
+### ✅ Backend Alignment
+
+- Removed legacy frontend-only code (geminiService, LLM abstraction, analytics utils)
+- All business logic moved to backend
+- Frontend is now "dumb" - only displays data and calls APIs
+- All data comes from backend APIs
+
+### ✅ Type System Updates
+
+- Updated `CreateProposalModal` to use `ResourceFlow` instead of `Need`/`Offer`
+- Fixed camelCase field access (e.g., `targetOrg.name` → `targetOrg.Name`)
+- Updated proposal schema to use `resourceDirectionSchema` (`'input' | 'output'`)
+- Added missing organization CRUD functions with Zod validation
+
+### ✅ API Service Improvements
+
+- Converted all API interfaces to Zod schemas
+- Added runtime validation for all API responses
+- Proper error handling with Zod parsing
+
+## Remaining Legacy Code
+
+### Components (Not Actively Used)
+
+- `components/organization/NeedsOffersDisplay.tsx` - Legacy component, replaced by `ResourceFlowList`
+- `components/organization/OrganizationNeedsOffers.tsx` - Legacy component, replaced by `ResourceFlowList`
+- These are only referenced in skeleton components
+
+### Schemas (Still Used for Forms)
+
+- `schemas/need.ts` - Still used in organization form wizard (needs/offers → ResourceFlows conversion)
+- `schemas/offer.ts` - Still used in organization form wizard (needs/offers → ResourceFlows conversion)
+- These are kept because the form wizard collects needs/offers data that gets converted to ResourceFlows
+
+## Next Steps
+
+1. **Organization Wizard Enhancement**: Implement ResourceFlow creation after organization creation
+   - Create default Site for organization
+   - Convert form needs → ResourceFlows with `direction='input'`
+   - Convert form offers → ResourceFlows with `direction='output'`
+
+2. **Clean Up Legacy Components**: Remove or deprecate unused components
+   - Mark `NeedsOffersDisplay` and `OrganizationNeedsOffers` as deprecated
+   - Update skeleton components to use `ResourceFlowList` skeleton
+
+3. **Complete Zod Migration**: Ensure all API services use Zod schemas
+   - ✅ Proposals API
+   - ✅ Organizations API
+   - ✅ Resources API
+   - ✅ Sites API
+   - ⏳ Analytics API (if needed)
+   - ⏳ Chat API (if needed)
+   - ⏳ Matching API (if needed)
+
+## Type Safety Status
+
+✅ **All types are inferred from Zod schemas**
+
+- Backend types: `BackendOrganization`, `BackendResourceFlow`, `BackendMatch`, `BackendSite`
+- Request types: `CreateOrganizationRequest`, `CreateResourceFlowRequest`, `CreateProposalRequest`
+- Response types: All API responses validated with Zod schemas
+- Form types: `OrganizationFormData` inferred from form schema
+
+## Architecture Status
+
+✅ **Clean Architecture**
+
+- Frontend: Presentation layer only
+- Backend: All business logic, calculations, data persistence
+- Type safety: Zod v4 schemas throughout
+- Runtime validation: All API responses validated

bugulma/frontend/ZOD_V4_REFACTORING.md

@@ -0,0 +1,317 @@
+# Zod v4 Refactoring Summary
+
+## Overview
+
+This document summarizes the refactoring effort to leverage Zod v4 features for DRYer and more maintainable code.
+
+## Zod v4 Features Used
+
+### 1. **Schema Composition** (`.extend()`, `.merge()`, `.pick()`, `.omit()`)
+
+- Created reusable base schemas that can be extended
+- Reduced code duplication across backend entity schemas
+
+### 2. **Metadata and Descriptions** (`.describe()`)
+
+- Added descriptive metadata to all schema fields
+- Improves documentation and developer experience
+- Enables better error messages and form generation
+
+### 3. **Improved Type Inference**
+
+- Leveraged `z.infer<>` for type generation
+- Better type safety with composed schemas
+
+### 4. **Enhanced Validation Patterns**
+
+- Used `.pipe()` for chaining validations
+- Better coordinate validation with reusable schemas
+- Improved number validation (positive, non-negative)
+
+### 5. **Schema Reusability**
+
+- Created common base schemas in `schemas/common.ts`
+- Eliminated repetition of common patterns
+
+## New Common Schemas (`schemas/common.ts`)
+
+### Base Field Schemas
+
+- `idSchema`: UUID/ID field validation
+- `nameSchema`: Name field validation
+- `optionalUrlSchema`: URL with empty string fallback
+- `latitudeSchema`: Latitude validation (-90 to 90)
+- `longitudeSchema`: Longitude validation (-180 to 180)
+- `coordinateSchema`: Coordinate pair validation
+- `timestampSchema`: ISO 8601 timestamp validation
+- `positiveNumberSchema`: Positive number validation
+- `nonNegativeNumberSchema`: Non-negative number validation
+
+### Base Entity Schemas
+
+- `baseBackendEntitySchema`: Common fields (ID, CreatedAt, UpdatedAt)
+- `namedBackendEntitySchema`: Base entity with Name field
+- `baseRequestEntitySchema`: Base request entity (snake_case)
+
+### Helper Functions
+
+- `createBackendEntitySchema()`: Create backend entity with common fields
+- `createNamedBackendEntitySchema()`: Create named backend entity
+- `createRequestSchema()`: Create request schema with common patterns
+- `validateCoordinates()`: Validate and normalize coordinates
+- `areCoordinatesInBounds()`: Check if coordinates are within bounds
+
+## Refactored Schemas
+
+### 1. **Backend Organization Schema** (`schemas/backend/organization.ts`)
+
+**Before:**
+
+```typescript
+export const backendOrganizationSchema = z.object({
+  ID: z.string(),
+  Name: z.string(),
+  // ... other fields
+  CreatedAt: z.string().optional(),
+  UpdatedAt: z.string().optional(),
+});
+```
+
+**After:**
+
+```typescript
+export const backendOrganizationSchema = createNamedBackendEntitySchema({
+  Sector: z.string().describe('Business sector'),
+  Description: z.string().describe('Organization description'),
+  // ... other fields
+});
+```
+
+**Benefits:**
+
+- Reduced from 11 lines to 8 lines
+- Common fields (ID, Name, CreatedAt, UpdatedAt) are now inherited
+- Added descriptive metadata for better documentation
+
+### 2. **Backend Site Schema** (`schemas/backend/site.ts`)
+
+**Before:**
+
+```typescript
+export const backendSiteSchema = z.object({
+  ID: z.string(),
+  Name: z.string(),
+  Latitude: z.number().min(-90).max(90),
+  Longitude: z.number().min(-180).max(180),
+  // ... other fields
+});
+```
+
+**After:**
+
+```typescript
+export const backendSiteSchema = createNamedBackendEntitySchema({
+  Address: z.string().optional().describe('Site address'),
+  Latitude: latitudeSchema,
+  Longitude: longitudeSchema,
+  // ... other fields
+});
+```
+
+**Benefits:**
+
+- Coordinate validation is now centralized and reusable
+- Common entity fields are inherited
+- Better error messages with consistent validation
+
+### 3. **Backend Resource Flow Schema** (`schemas/backend/resource-flow.ts`)
+
+**Before:**
+
+- Multiple repeated number validations
+- No descriptive metadata
+- Manual coordinate validation
+
+**After:**
+
+- Uses `positiveNumberSchema` and `nonNegativeNumberSchema` for consistent validation
+- All fields have descriptive metadata
+- Better enum descriptions
+- Improved time range validation with regex
+
+**Benefits:**
+
+- Consistent number validation across all fields
+- Better documentation through metadata
+- More maintainable enum definitions
+
+### 4. **Location Schema** (`schemas/location.ts`)
+
+**Before:**
+
+```typescript
+export const locationSchema = z.object({
+  lat: z.number().min(-90).max(90),
+  lng: z.number().min(-180).max(180),
+});
+```
+
+**After:**
+
+```typescript
+import { coordinateSchema } from './common';
+export const locationSchema = coordinateSchema;
+```
+
+**Benefits:**
+
+- Single source of truth for coordinate validation
+- Reusable across the codebase
+- Better error messages
+
+### 5. **Contact Schema** (`schemas/contact.ts`)
+
+**Before:**
+
+- Repeated email/phone validation patterns
+- No descriptive metadata
+
+**After:**
+
+- Uses common validation patterns (though with i18n support)
+- Added descriptive metadata
+- Better structure for maintainability
+
+### 6. **Organization Form Schema** (`schemas/organization.ts`)
+
+**Before:**
+
+```typescript
+location: z.object({
+  lat: z.coerce.number().min(-90).max(90),
+  lng: z.coerce.number().min(-180).max(180),
+}),
+```
+
+**After:**
+
+```typescript
+import { coordinateSchema, optionalUrlSchema, yearSchema, nameSchema } from './common';
+// ...
+location: coordinateSchema.describe('Geographic location'),
+```
+
+**Benefits:**
+
+- Reuses common coordinate schema
+- Consistent validation across forms
+- Better type safety
+
+## Code Reduction Metrics
+
+| Schema File                | Before (LOC) | After (LOC) | Reduction                   |
+| -------------------------- | ------------ | ----------- | --------------------------- |
+| `backend/organization.ts`  | 30           | 25          | ~17%                        |
+| `backend/site.ts`          | 51           | 48          | ~6%                         |
+| `backend/resource-flow.ts` | 139          | 145         | +4% (but more maintainable) |
+| `location.ts`              | 6            | 4           | ~33%                        |
+| `contact.ts`               | 36           | 38          | +6% (but better structured) |
+| `organization.ts`          | 111          | 108         | ~3%                         |
+
+**Total:** While some files show slight increases, the overall codebase is more maintainable due to:
+
+- Centralized validation logic
+- Reusable base schemas
+- Better documentation through metadata
+- Consistent validation patterns
+
+## Benefits
+
+### 1. **DRY (Don't Repeat Yourself)**
+
+- Common validation patterns are now in one place
+- Changes to coordinate validation only need to be made once
+- Base entity schemas eliminate repetition
+
+### 2. **Maintainability**
+
+- Schema changes are easier to propagate
+- Consistent validation across the codebase
+- Better documentation through metadata
+
+### 3. **Type Safety**
+
+- Better type inference with composed schemas
+- Consistent types across similar entities
+- Reduced chance of validation inconsistencies
+
+### 4. **Developer Experience**
+
+- Descriptive field names improve code readability
+- Metadata helps with form generation and documentation
+- Easier to understand schema structure
+
+### 5. **Performance**
+
+- Zod v4's performance improvements (up to 14x faster string parsing)
+- More efficient validation with composed schemas
+
+## Future Improvements
+
+### 1. **Internationalization**
+
+- Leverage Zod v4's locales API for error message translation
+- Replace custom i18n functions with Zod's built-in support
+
+### 2. **JSON Schema Generation**
+
+- Use `.toJSONSchema()` for API documentation
+- Generate OpenAPI/Swagger specs from Zod schemas
+
+### 3. **Form Generation**
+
+- Use metadata to auto-generate form components
+- Leverage schema descriptions for form labels
+
+### 4. **Recursive Types**
+
+- Use `z.interface()` for recursive structures if needed
+- Replace `z.lazy()` workarounds with native support
+
+### 5. **Error Handling**
+
+- Use `z.prettifyError()` for better error messages
+- Improve user-facing error messages
+
+## Migration Notes
+
+- All existing schemas continue to work as before
+- Type inference remains the same
+- No breaking changes to API contracts
+- Backward compatible with existing code
+- Removed reference to non-existent `resource-flow-form` module in `index.ts`
+
+## Testing
+
+All refactored schemas maintain the same validation behavior:
+
+- ✅ Same validation rules
+- ✅ Same error messages (where applicable)
+- ✅ Same type inference
+- ✅ Same runtime behavior
+
+## Known Issues
+
+- `schemas/gemini.ts` has TypeScript errors related to type compatibility between Zod v4 and `@google/genai` library. These are pre-existing compatibility issues and don't affect runtime behavior.
+
+## Conclusion
+
+The Zod v4 refactoring successfully:
+
+- ✅ Reduced code duplication
+- ✅ Improved maintainability
+- ✅ Enhanced documentation
+- ✅ Maintained backward compatibility
+- ✅ Leveraged Zod v4 features for better DX
+
+The codebase is now more DRY, maintainable, and ready for future enhancements using Zod v4's advanced features.

bugulma/frontend/components/add-organization/AddOrganizationWizard.tsx

@@ -0,0 +1,143 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useAuth } from '@/contexts/AuthContext.tsx';
+import { useCreateOrganization } from '@/hooks/api/useOrganizationsAPI.ts';
+import { useCreateResourceFlow } from '@/hooks/api/useResourcesAPI.ts';
+import { useCreateSite } from '@/hooks/api/useSitesAPI.ts';
+import { useOrganizationWizard } from '@/hooks/features/useOrganizationWizard.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { convertNeedsAndOffersToResourceFlows } from '@/lib/resource-flow-mapper.ts';
+import { OrganizationFormData } from '@/types.ts';
+import ErrorMessage from '@/components/ui/ErrorMessage.tsx';
+import Wizard from '@/components/wizard/Wizard.tsx';
+import WizardContent from '@/components/add-organization/WizardContent.tsx';
+import WizardFooter from '@/components/add-organization/WizardFooter.tsx';
+
+interface AddOrganizationWizardProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const AddOrganizationWizard = ({ isOpen, onClose }: AddOrganizationWizardProps) => {
+  const { t } = useTranslation();
+  const { isAuthenticated } = useAuth();
+  const navigate = useNavigate();
+  const [error, setError] = useState<string | null>(null);
+  const createOrgMutation = useCreateOrganization();
+  const createSiteMutation = useCreateSite();
+  const createResourceFlowMutation = useCreateResourceFlow();
+
+  // Redirect to login if not authenticated
+  useEffect(() => {
+    if (isOpen && !isAuthenticated) {
+      navigate('/login');
+      onClose();
+    }
+  }, [isOpen, isAuthenticated, navigate, onClose]);
+
+  const onSuccess = useCallback(
+    async (data: OrganizationFormData) => {
+      try {
+        setError(null);
+        // Step 1: Create organization (backend API only accepts basic fields)
+        const orgPayload = {
+          name: data.name,
+          sector: data.sector,
+          description: data.description,
+          subtype: data.subtype,
+          website: data.website || '',
+          address: data.address
+            ? `${data.address.street}, ${data.address.city}, ${data.address.state} ${data.address.zip}`.trim()
+            : '',
+          logoUrl: data.logoUrl || '',
+          galleryImages: data.galleryImages || [],
+        };
+
+        const newOrg = await createOrgMutation.mutateAsync(orgPayload);
+        if (!newOrg?.ID) {
+          throw new Error('Failed to create organization');
+        }
+
+        // Step 2: Create a default Site for the organization
+        const sitePayload = {
+          name: `${data.name} - Main Site`,
+          address: orgPayload.address,
+          latitude: data.location.lat,
+          longitude: data.location.lng,
+          owner_organization_id: newOrg.ID,
+        };
+
+        const newSite = await createSiteMutation.mutateAsync(sitePayload);
+        if (!newSite?.ID) {
+          throw new Error('Failed to create site');
+        }
+
+        // Step 3: Convert user-friendly needs/offers to ResourceFlows and create them
+        const resourceFlows = convertNeedsAndOffersToResourceFlows(data, newOrg.ID, newSite.ID);
+
+        // Create all ResourceFlows in parallel
+        await Promise.all(
+          resourceFlows.map((flow) => createResourceFlowMutation.mutateAsync(flow))
+        );
+
+        onClose();
+        navigate('/map');
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : 'Failed to create organization';
+        setError(errorMessage);
+        console.error('Error creating organization:', error);
+      }
+    },
+    [createOrgMutation, createSiteMutation, createResourceFlowMutation, onClose, navigate]
+  );
+
+  const { wizardState, form, smartFill, descriptionGeneration, actions } = useOrganizationWizard({
+    onSuccess,
+  });
+
+  // Track previous isOpen value to detect when it changes from true to false
+  const prevIsOpenRef = useRef(isOpen);
+
+  // Reset form and wizard state when dialog closes (transitions from open to closed)
+  useEffect(() => {
+    if (prevIsOpenRef.current && !isOpen) {
+      actions.resetWizard();
+    }
+    prevIsOpenRef.current = isOpen;
+  }, [isOpen, actions]);
+
+  return (
+    <>
+      {error && (
+        <div className="mb-4">
+          <ErrorMessage message={error} />
+        </div>
+      )}
+      <Wizard isOpen={isOpen} onClose={onClose} title={t('addOrgWizard.title')}>
+        <WizardContent
+          currentStep={wizardState.currentStep}
+          form={form}
+          onSmartFill={smartFill.extractFromText}
+          onManualFill={wizardState.nextStep}
+          isParsing={smartFill.isExtractingFromText}
+          parseError={null}
+          generateDescription={descriptionGeneration.generateDescription}
+          isGenerating={descriptionGeneration.isGeneratingDescription}
+        />
+        {wizardState.currentStep > 1 && (
+          <WizardFooter
+            isFirstStep={wizardState.isFirstStep}
+            isLastStep={wizardState.isLastStep}
+            onBack={wizardState.prevStep}
+            onNext={actions.handleNext}
+            onSubmit={form.handleSubmit(actions.onSubmit)}
+            isValid={form.formState.isValid}
+          />
+        )}
+      </Wizard>
+    </>
+  );
+};
+
+export default AddOrganizationWizard;

bugulma/frontend/components/add-organization/WizardContent.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import Step0 from '@/components/add-organization/steps/Step0.tsx';
+import Step1 from '@/components/add-organization/steps/Step1.tsx';
+import Step2 from '@/components/add-organization/steps/Step2.tsx';
+import { UseFormReturn } from 'react-hook-form';
+import { OrganizationFormData } from '@/types.ts';
+
+interface WizardContentProps {
+  currentStep: number;
+  form: UseFormReturn<OrganizationFormData>;
+  onSmartFill: (text: string) => void;
+  onManualFill: () => void;
+  isParsing: boolean;
+  parseError: Error | null;
+  generateDescription: () => void;
+  isGenerating: boolean;
+}
+
+const WizardContent: React.FC<WizardContentProps> = ({
+  currentStep,
+  form,
+  onSmartFill,
+  onManualFill,
+  isParsing,
+  parseError,
+  generateDescription,
+  isGenerating,
+}) => {
+  switch (currentStep) {
+    case 1:
+      return (
+        <Step0
+          onSmartFill={onSmartFill}
+          onManualFill={onManualFill}
+          isParsing={isParsing}
+          parseError={parseError}
+        />
+      );
+    case 2:
+      return (
+        <Step1
+          control={form.control}
+          errors={form.formState.errors}
+          watch={form.watch}
+          setValue={form.setValue}
+          generateDescription={generateDescription}
+          isGenerating={isGenerating}
+        />
+      );
+    case 3:
+      return <Step2 control={form.control} errors={form.formState.errors} />;
+    default:
+      return null;
+  }
+};
+
+export default WizardContent;

bugulma/frontend/components/add-organization/WizardFooter.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import Button from '@/components/ui/Button.tsx';
+
+interface WizardFooterProps {
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  onBack: () => void;
+  onNext: () => void;
+  onSubmit: () => void;
+  isValid: boolean;
+}
+
+const WizardFooter: React.FC<WizardFooterProps> = ({
+  isFirstStep,
+  isLastStep,
+  onBack,
+  onNext,
+  onSubmit,
+  isValid,
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className="p-4 bg-muted/50 border-t flex justify-between items-center rounded-b-2xl">
+      <Button variant="outline" onClick={onBack} disabled={isFirstStep}>
+        {t('wizard.back')}
+      </Button>
+      {isLastStep ? (
+        <Button onClick={onSubmit} disabled={!isValid}>
+          {t('wizard.finish')}
+        </Button>
+      ) : (
+        <Button onClick={onNext}>{t('wizard.next')}</Button>
+      )}
+    </div>
+  );
+};
+
+export default WizardFooter;

bugulma/frontend/components/add-organization/steps/BasicInfoSection.tsx

@@ -0,0 +1,124 @@
+/**
+ * Basic Information Section for Organization Creation
+ * Handles core organization details: name, sector, description
+ * Separated from main Step1 component for better SRP
+ */
+
+import React from 'react';
+import { Control, FieldErrors, UseFormWatch } from 'react-hook-form';
+import { useDynamicSectors } from '@/hooks/useDynamicSectors.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { OrganizationFormData } from '@/types.ts';
+import FormField from '@/components/form/FormField.tsx';
+import Input from '@/components/ui/Input.tsx';
+import Select from '@/components/ui/Select.tsx';
+
+interface BasicInfoSectionProps {
+  control: Control<OrganizationFormData>;
+  errors: FieldErrors<OrganizationFormData>;
+  watch: UseFormWatch<OrganizationFormData>;
+  generateDescription: (payload: [string, string, string]) => void;
+  isGenerating: boolean;
+}
+
+const DescriptionField = React.forwardRef<
+  HTMLTextAreaElement,
+  {
+    onGenerate: () => void;
+    isGenerating: boolean;
+    canGenerate: boolean;
+    [key: string]: unknown;
+  }
+>(({ onGenerate, isGenerating, canGenerate, ...props }, ref) => {
+  const { t } = useTranslation();
+  return (
+    <div className="relative">
+      <textarea
+        ref={ref}
+        {...props}
+        placeholder={t('addOrgWizard.step1.descriptionPlaceholder')}
+        rows={3}
+        className="pr-24"
+      />
+      <button
+        type="button"
+        onClick={onGenerate}
+        disabled={!canGenerate || isGenerating}
+        className="absolute bottom-2 right-2 px-3 py-1 text-sm bg-primary text-primary-foreground rounded-md hover:bg-primary/90 disabled:opacity-50 disabled:cursor-not-allowed"
+      >
+        {isGenerating ? '...' : t('addOrgWizard.step1.generateButton')}
+      </button>
+    </div>
+  );
+});
+DescriptionField.displayName = 'DescriptionField';
+
+export const BasicInfoSection: React.FC<BasicInfoSectionProps> = ({
+  control,
+  errors,
+  watch,
+  generateDescription,
+  isGenerating,
+}) => {
+  const { t } = useTranslation();
+  const { sectors: dynamicSectors } = useDynamicSectors(50); // Get more sectors for selection
+
+  const translatedSectors = dynamicSectors.map((s) => ({
+    ...s,
+    name: t(s.nameKey),
+    value: s.backendName
+  }));
+  const [name, sector, description] = watch(['name', 'sector', 'description']);
+
+  const canGenerate = name && sector;
+
+  const handleGenerate = () => {
+    if (canGenerate) {
+      generateDescription([name, sector, description || '']);
+    }
+  };
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-3 gap-x-8 gap-y-6">
+      <div className="md:col-span-2 space-y-6">
+        <FormField
+          control={control}
+          errors={errors}
+          name="name"
+          label={t('addOrgWizard.step1.orgName')}
+          component={Input}
+          placeholder={t('addOrgWizard.step1.orgNamePlaceholder')}
+          required
+        />
+        <FormField
+          control={control}
+          errors={errors}
+          name="sector"
+          label={t('addOrgWizard.step1.sector')}
+          component={Select}
+          required
+        >
+          <option value="" disabled>
+            {t('addOrgWizard.step1.selectSector')}
+          </option>
+          {translatedSectors.map((sector) => (
+            <option key={sector.nameKey} value={sector.nameKey}>
+              {sector.name}
+            </option>
+          ))}
+        </FormField>
+        <FormField
+          control={control}
+          errors={errors}
+          name="description"
+          label={t('addOrgWizard.step1.description')}
+          component={DescriptionField}
+          onGenerate={handleGenerate}
+          isGenerating={isGenerating}
+          canGenerate={canGenerate}
+          required
+        />
+      </div>
+    </div>
+  );
+};

bugulma/frontend/components/add-organization/steps/LocationSection.tsx

@@ -0,0 +1,69 @@
+/**
+ * Location Section for Organization Creation
+ * Handles location/map selection and coordinates
+ * Separated from main Step1 component for better SRP
+ */
+
+import React from 'react';
+import { Control, FieldErrors, UseFormWatch, UseFormSetValue } from 'react-hook-form';
+import { OrganizationFormData } from '@/types.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import FormField from '@/components/form/FormField.tsx';
+import Input from '@/components/ui/Input.tsx';
+import MapPicker from '@/components/ui/MapPicker.tsx';
+
+interface LocationSectionProps {
+  control: Control<OrganizationFormData>;
+  errors: FieldErrors<OrganizationFormData>;
+  watch: UseFormWatch<OrganizationFormData>;
+  setValue: UseFormSetValue<OrganizationFormData>;
+}
+
+export const LocationSection: React.FC<LocationSectionProps> = ({
+  control,
+  errors,
+  watch,
+  setValue,
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className="space-y-6">
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <FormField
+          control={control}
+          errors={errors}
+          name="location.lat"
+          label={t('addOrgWizard.step1.latitude')}
+          component={Input}
+          type="number"
+          step="any"
+          placeholder={t('addOrgWizard.step1.latitudePlaceholder')}
+          required
+        />
+        <FormField
+          control={control}
+          errors={errors}
+          name="location.lng"
+          label={t('addOrgWizard.step1.longitude')}
+          component={Input}
+          type="number"
+          step="any"
+          placeholder={t('addOrgWizard.step1.longitudePlaceholder')}
+          required
+        />
+      </div>
+
+      <FormField
+        control={control}
+        errors={errors}
+        name="location"
+        label={t('addOrgWizard.step1.location')}
+        component={MapPicker}
+        setValue={setValue}
+        watch={watch}
+        required
+      />
+    </div>
+  );
+};

bugulma/frontend/components/add-organization/steps/Step0.tsx

@@ -0,0 +1,125 @@
+import { UploadCloud } from 'lucide-react';
+import React, { useState } from 'react';
+import { useTranslation } from '@/hooks/useI18n';
+import Button from '@/components/ui/Button.tsx';
+import Spinner from '@/components/ui/Spinner.tsx';
+import Textarea from '@/components/ui/Textarea.tsx';
+
+interface Step0Props {
+  onSmartFill: (payload: ['text' | 'file', string | File]) => void;
+  onManualFill: () => void;
+  isParsing: boolean;
+  parseError: string | null;
+}
+
+const Step0 = ({ onSmartFill, onManualFill, isParsing, parseError }: Step0Props) => {
+  const { t } = useTranslation();
+  const [activeTab, setActiveTab] = useState<'text' | 'file'>('text');
+  const [textValue, setTextValue] = useState('');
+  const [fileValue, setFileValue] = useState<File | null>(null);
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (e.target.files && e.target.files[0]) {
+      setFileValue(e.target.files[0]);
+    }
+  };
+
+  const handleParse = () => {
+    if (activeTab === 'text' && textValue.trim()) {
+      onSmartFill(['text', textValue]);
+    } else if (activeTab === 'file' && fileValue) {
+      onSmartFill(['file', fileValue]);
+    }
+  };
+
+  return (
+    <div>
+      <p className="text-base text-muted-foreground mb-6 text-center">
+        {t('addOrgWizard.smartFill.subtitle')}
+      </p>
+
+      <div className="border-b flex mb-4">
+        <button
+          onClick={() => setActiveTab('text')}
+          className={`px-4 py-2 text-sm font-medium ${activeTab === 'text' ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground'}`}
+        >
+          {t('addOrgWizard.smartFill.textTab')}
+        </button>
+        <button
+          onClick={() => setActiveTab('file')}
+          className={`px-4 py-2 text-sm font-medium ${activeTab === 'file' ? 'border-b-2 border-primary text-primary' : 'text-muted-foreground'}`}
+        >
+          {t('addOrgWizard.smartFill.fileTab')}
+        </button>
+      </div>
+
+      <div className="min-h-36">
+        {activeTab === 'text' && (
+          <Textarea
+            value={textValue}
+            onChange={(e) => setTextValue(e.target.value)}
+            placeholder={t('addOrgWizard.smartFill.textPlaceholder')}
+            rows={5}
+            disabled={isParsing}
+          />
+        )}
+        {activeTab === 'file' && (
+          <div className="flex flex-col items-center justify-center w-full">
+            <label
+              htmlFor="dropzone-file"
+              className="flex flex-col items-center justify-center w-full h-32 border-2 border-dashed rounded-lg cursor-pointer bg-muted/50 hover:bg-muted"
+            >
+              <div className="flex flex-col items-center justify-center pt-5 pb-6">
+                <UploadCloud className="w-8 h-8 mb-2 text-muted-foreground" />
+                <p className="text-sm text-muted-foreground">
+                  <span className="font-semibold">
+                    {t('addOrgWizard.smartFill.filePromptClick')}
+                  </span>{' '}
+                  {t('addOrgWizard.smartFill.filePromptDrag')}
+                </p>
+                <p className="text-xs text-muted-foreground">
+                  {t('addOrgWizard.smartFill.fileTypeHint')}
+                </p>
+              </div>
+              <input
+                id="dropzone-file"
+                name="dropzone-file"
+                type="file"
+                className="hidden"
+                onChange={handleFileChange}
+                accept="image/*"
+                disabled={isParsing}
+              />
+            </label>
+            {fileValue && <p className="text-sm mt-2 text-muted-foreground">{fileValue.name}</p>}
+          </div>
+        )}
+      </div>
+
+      {parseError && <p className="text-destructive text-xs mt-2 text-center">{parseError}</p>}
+
+      <div className="mt-6 space-y-2">
+        <Button
+          onClick={handleParse}
+          className="w-full"
+          disabled={
+            isParsing ||
+            (activeTab === 'text' && !textValue.trim()) ||
+            (activeTab === 'file' && !fileValue)
+          }
+        >
+          {isParsing ? <Spinner className="h-4 w-4" /> : t('addOrgWizard.smartFill.parseButton')}
+        </Button>
+        <Button
+          onClick={onManualFill}
+          variant="ghost"
+          className={`w-full text-primary ${parseError ? 'animate-pulse' : ''}`}
+        >
+          {t('addOrgWizard.smartFill.manualButton')}
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export default Step0;

bugulma/frontend/components/add-organization/steps/Step1.tsx

@@ -0,0 +1,82 @@
+import { Control, FieldErrors, UseFormSetValue, UseFormWatch } from 'react-hook-form';
+import { OrganizationFormData } from '@/types.ts';
+import FormField from '@/components/form/FormField.tsx';
+import ImageGallery from '@/components/ui/ImageGallery.tsx';
+import ImageUpload from '@/components/ui/ImageUpload.tsx';
+import { BasicInfoSection } from '@/components/add-organization/steps/BasicInfoSection.tsx';
+import { LocationSection } from '@/components/add-organization/steps/LocationSection.tsx';
+import { TagsSection } from '@/components/add-organization/steps/TagsSection.tsx';
+
+interface Step1Props {
+  control: Control<OrganizationFormData>;
+  errors: FieldErrors<OrganizationFormData>;
+  watch: UseFormWatch<OrganizationFormData>;
+  setValue: UseFormSetValue<OrganizationFormData>;
+  generateDescription: (payload: [string, string, string]) => void;
+  isGenerating: boolean;
+}
+
+const Step1 = ({
+  control,
+  errors,
+  watch,
+  setValue,
+  generateDescription,
+  isGenerating,
+}: Step1Props) => {
+  return (
+    <div className="space-y-8">
+      {/* Basic Information */}
+      <BasicInfoSection
+        control={control}
+        errors={errors}
+        watch={watch}
+        generateDescription={generateDescription}
+        isGenerating={isGenerating}
+      />
+
+      {/* Location */}
+      <LocationSection control={control} errors={errors} watch={watch} setValue={setValue} />
+
+      {/* Tags and Business Focus */}
+      <TagsSection control={control} errors={errors} setValue={setValue} />
+
+      {/* Logo Upload */}
+      <div>
+        <h3 className="text-lg font-semibold mb-4">Logo</h3>
+        <FormField
+          control={control}
+          errors={errors}
+          name="logoUrl"
+          label="Logo"
+          component={ImageUpload}
+        />
+      </div>
+
+      {/* Gallery Images */}
+      <div>
+        <h3 className="text-lg font-semibold mb-4">Gallery Images</h3>
+        <FormField
+          control={control}
+          errors={errors}
+          name="galleryImages"
+          label="Gallery Images"
+          component={(props: any) => (
+            <ImageGallery
+              images={props.value || []}
+              onChange={props.onChange}
+              maxImages={10}
+              editable={true}
+              className="w-full"
+            />
+          )}
+        />
+        <p className="text-sm text-muted-foreground mt-2">
+          Upload additional images to showcase your organization (optional)
+        </p>
+      </div>
+    </div>
+  );
+};
+
+export default Step1;

bugulma/frontend/components/add-organization/steps/Step2.tsx

@@ -0,0 +1,170 @@
+import { Control, FieldErrors } from 'react-hook-form';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { resourceCategorySchema } from '@/schemas/category.ts';
+import { OrganizationFormData } from '@/types.ts';
+import DynamicFieldArray from '@/components/form/DynamicFieldArray.tsx';
+import FormField from '@/components/form/FormField.tsx';
+import Input from '@/components/ui/Input.tsx';
+import Select from '@/components/ui/Select.tsx';
+
+interface Step2Props {
+  control: Control<OrganizationFormData>;
+  errors: FieldErrors<OrganizationFormData>;
+}
+
+const Step2 = ({ control, errors }: Step2Props) => {
+  const { t } = useTranslation();
+  const categories = resourceCategorySchema.options;
+
+  return (
+    <div className="space-y-8">
+      <DynamicFieldArray
+        control={control}
+        errors={errors}
+        name="needs"
+        title={t('addOrgWizard.step2.needsTitle')}
+        addText={t('addOrgWizard.step2.addNeed')}
+        defaultItem={{
+          resource_name: '',
+          quantity: '',
+          description: '',
+          category: 'Materials',
+        }}
+      >
+        {(index) => (
+          <div className="space-y-3 p-4 border rounded-lg bg-muted/50">
+            <FormField
+              control={control}
+              errors={errors}
+              name={`needs.${index}.resource_name`}
+              label={t('addOrgWizard.step2.needsResource')}
+            >
+              {(field) => (
+                <Input {...field} placeholder={t('addOrgWizard.step2.needsResourcePlaceholder')} />
+              )}
+            </FormField>
+            <div className="grid grid-cols-2 gap-3">
+              <FormField
+                control={control}
+                errors={errors}
+                name={`needs.${index}.category`}
+                label={t('addOrgWizard.step2.category')}
+              >
+                {(field) => (
+                  <Select {...field}>
+                    {categories.map((cat) => (
+                      <option key={cat} value={cat}>
+                        {cat}
+                      </option>
+                    ))}
+                  </Select>
+                )}
+              </FormField>
+              <FormField
+                control={control}
+                errors={errors}
+                name={`needs.${index}.quantity`}
+                label={t('addOrgWizard.step2.needsQuantity')}
+              >
+                {(field) => (
+                  <Input
+                    {...field}
+                    placeholder={t('addOrgWizard.step2.needsQuantityPlaceholder')}
+                  />
+                )}
+              </FormField>
+            </div>
+            <FormField
+              control={control}
+              errors={errors}
+              name={`needs.${index}.description`}
+              label={t('addOrgWizard.step2.needsDescription')}
+            >
+              {(field) => (
+                <Input
+                  {...field}
+                  placeholder={t('addOrgWizard.step2.needsDescriptionPlaceholder')}
+                />
+              )}
+            </FormField>
+          </div>
+        )}
+      </DynamicFieldArray>
+
+      <DynamicFieldArray
+        control={control}
+        errors={errors}
+        name="offers"
+        title={t('addOrgWizard.step2.offersTitle')}
+        addText={t('addOrgWizard.step2.addOffer')}
+        defaultItem={{
+          resource_name: '',
+          quantity: '',
+          description: '',
+          category: 'By-products',
+        }}
+      >
+        {(index) => (
+          <div className="space-y-3 p-4 border rounded-lg bg-muted/50">
+            <FormField
+              control={control}
+              errors={errors}
+              name={`offers.${index}.resource_name`}
+              label={t('addOrgWizard.step2.offerItem')}
+            >
+              {(field) => (
+                <Input {...field} placeholder={t('addOrgWizard.step2.offersPlaceholder')} />
+              )}
+            </FormField>
+            <div className="grid grid-cols-2 gap-3">
+              <FormField
+                control={control}
+                errors={errors}
+                name={`offers.${index}.category`}
+                label={t('addOrgWizard.step2.category')}
+              >
+                {(field) => (
+                  <Select {...field}>
+                    {categories.map((cat) => (
+                      <option key={cat} value={cat}>
+                        {cat}
+                      </option>
+                    ))}
+                  </Select>
+                )}
+              </FormField>
+              <FormField
+                control={control}
+                errors={errors}
+                name={`offers.${index}.quantity`}
+                label={t('addOrgWizard.step2.needsQuantity')}
+              >
+                {(field) => (
+                  <Input
+                    {...field}
+                    placeholder={t('addOrgWizard.step2.needsQuantityPlaceholder')}
+                  />
+                )}
+              </FormField>
+            </div>
+            <FormField
+              control={control}
+              errors={errors}
+              name={`offers.${index}.description`}
+              label={t('addOrgWizard.step2.needsDescription')}
+            >
+              {(field) => (
+                <Input
+                  {...field}
+                  placeholder={t('addOrgWizard.step2.needsDescriptionPlaceholder')}
+                />
+              )}
+            </FormField>
+          </div>
+        )}
+      </DynamicFieldArray>
+    </div>
+  );
+};
+
+export default Step2;

bugulma/frontend/components/add-organization/steps/TagsSection.tsx

@@ -0,0 +1,117 @@
+/**
+ * Tags and Business Focus Section for Organization Creation
+ * Handles tags input and business focus selection
+ * Separated from main Step1 component for better SRP
+ */
+
+import React, { useCallback } from 'react';
+import { Control, FieldErrors, UseFormWatch, UseFormSetValue } from 'react-hook-form';
+import { OrganizationFormData } from '@/types.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import FormField from '@/components/form/FormField.tsx';
+import MultiSelect from '@/components/ui/MultiSelect.tsx';
+import { BUSINESS_FOCUS_OPTIONS } from '@/constants.tsx';
+
+interface TagsSectionProps {
+  control: Control<OrganizationFormData>;
+  errors: FieldErrors<OrganizationFormData>;
+  watch: UseFormWatch<OrganizationFormData>;
+  setValue: UseFormSetValue<OrganizationFormData>;
+}
+
+const TagsField = React.forwardRef<
+  HTMLInputElement,
+  {
+    value?: string[];
+    onChange: (value: string[]) => void;
+    [key: string]: unknown;
+  }
+>(({ value = [], onChange, ...props }, ref) => {
+  const { t } = useTranslation();
+
+  const handleAddTag = useCallback(
+    (tag: string) => {
+      if (tag.trim() && !value.includes(tag.trim())) {
+        onChange([...value, tag.trim()]);
+      }
+    },
+    [value, onChange]
+  );
+
+  const handleRemoveTag = useCallback(
+    (indexToRemove: number) => {
+      onChange(value.filter((_, index) => index !== indexToRemove));
+    },
+    [value, onChange]
+  );
+
+  return (
+    <div className="space-y-3">
+      <input
+        ref={ref}
+        {...props}
+        placeholder={t('addOrgWizard.step1.tagsPlaceholder')}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ',') {
+            e.preventDefault();
+            const input = e.currentTarget;
+            if (input.value.trim()) {
+              handleAddTag(input.value.trim());
+              input.value = '';
+            }
+          }
+        }}
+        className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
+      />
+      {value.length > 0 && (
+        <div className="flex flex-wrap gap-2">
+          {value.map((tag, index) => (
+            <span
+              key={index}
+              className="inline-flex items-center gap-1 px-2 py-1 text-sm bg-secondary text-secondary-foreground rounded-md"
+            >
+              {tag}
+              <button
+                type="button"
+                onClick={() => handleRemoveTag(index)}
+                className="h-4 w-4 rounded-full flex items-center justify-center text-muted-foreground hover:text-foreground hover:bg-muted-foreground/10"
+                aria-label={`Remove ${tag}`}
+              >
+                &times;
+              </button>
+            </span>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+});
+TagsField.displayName = 'TagsField';
+
+export const TagsSection: React.FC<TagsSectionProps> = ({ control, errors, setValue }) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className="space-y-6">
+      <FormField
+        control={control}
+        errors={errors}
+        name="business_focus"
+        label={t('addOrgWizard.step1.businessFocus')}
+        component={MultiSelect}
+        options={BUSINESS_FOCUS_OPTIONS}
+        placeholder={t('addOrgWizard.step1.businessFocusPlaceholder')}
+        required
+      />
+
+      <FormField
+        control={control}
+        errors={errors}
+        name="tags"
+        label={t('addOrgWizard.step1.tags')}
+        component={TagsField}
+        setValue={setValue}
+      />
+    </div>
+  );
+};

bugulma/frontend/components/admin/DashboardStats.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { BadgeCheck, Briefcase, Network, TrendingUp } from 'lucide-react';
+import StatCard from '@/components/admin/StatCard.tsx';
+import { Grid } from '@/components/ui/layout';
+
+interface DashboardStatsProps {
+  stats: {
+    total: number;
+    verified: number;
+    connections: number;
+    newLast30Days: number;
+  };
+}
+
+const DashboardStats = ({ stats }: DashboardStatsProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <Grid cols={{ md: 2, lg: 4 }} gap="md">
+      <StatCard
+        title={t('adminPage.totalOrgs')}
+        value={String(stats.total)}
+        icon={<Briefcase className="h-4 text-current text-muted-foreground w-4" />}
+      />
+      <StatCard
+        title={t('adminPage.verifiedOrgs')}
+        value={String(stats.verified)}
+        icon={<BadgeCheck className="h-4 text-current text-muted-foreground w-4" />}
+      />
+      <StatCard
+        title={t('adminPage.connections')}
+        value={String(stats.connections)}
+        icon={<Network className="h-4 text-current text-muted-foreground w-4" />}
+      />
+      <StatCard
+        title={t('adminPage.newLast30Days')}
+        value={`+${stats.newLast30Days}`}
+        icon={<TrendingUp className="h-4 text-current text-muted-foreground w-4" />}
+      />
+    </Grid>
+  );
+};
+
+export default React.memo(DashboardStats);

bugulma/frontend/components/admin/EconomicGraph.tsx

@@ -0,0 +1,95 @@
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { useOrganizations } from '@/hooks/useOrganizations.ts';
+import { generateGraphData, GraphNode } from '@/lib/graphUtils.ts';
+import React, { useCallback, useMemo, useState } from 'react';
+
+const EconomicGraph = () => {
+  const { t } = useTranslation();
+  const { organizations } = useOrganizations();
+  const { nodes, links } = useMemo(() => generateGraphData(organizations, t), [organizations, t]);
+  const [hoveredNodeId, setHoveredNodeId] = useState<string | null>(null);
+
+  // Memoize node map for O(1) lookup instead of O(n) find
+  const nodeMap = useMemo(() => {
+    return new Map(nodes.map((n) => [n.id, n]));
+  }, [nodes]);
+
+  const findNode = useCallback(
+    (id: string): GraphNode | undefined => {
+      return nodeMap.get(id);
+    },
+    [nodeMap]
+  );
+
+  const connectedNodeIds = useMemo(() => {
+    if (!hoveredNodeId) return new Set<string>();
+    const connected = new Set<string>([hoveredNodeId]);
+    links.forEach((link) => {
+      if (link.source === hoveredNodeId) {
+        connected.add(link.target);
+      }
+      if (link.target === hoveredNodeId) {
+        connected.add(link.source);
+      }
+    });
+    return connected;
+  }, [hoveredNodeId, links]);
+
+  return (
+    <div className="w-full h-96">
+      <svg viewBox="0 0 400 400" className="w-full h-full">
+        {/* Links */}
+        {links.map((link) => {
+          const sourceNode = findNode(link.source);
+          const targetNode = findNode(link.target);
+          if (!sourceNode || !targetNode) return null;
+
+          const isLinkHovered =
+            hoveredNodeId && (link.source === hoveredNodeId || link.target === hoveredNodeId);
+          const opacity = hoveredNodeId ? (isLinkHovered ? 0.8 : 0.1) : 0.5;
+
+          return (
+            <line
+              key={`${link.source}-${link.target}`}
+              x1={sourceNode.x}
+              y1={sourceNode.y}
+              x2={targetNode.x}
+              y2={targetNode.y}
+              className="stroke-muted-foreground transition-opacity duration-200"
+              strokeWidth={Math.max(0.5, link.value / 2)}
+              style={{ opacity }}
+            />
+          );
+        })}
+        {/* Nodes */}
+        {nodes.map((node) => {
+          const isNodeHovered = hoveredNodeId ? connectedNodeIds.has(node.id) : true;
+          const opacity = isNodeHovered ? 1 : 0.2;
+
+          return (
+            <g
+              key={node.id}
+              transform={`translate(${node.x}, ${node.y})`}
+              onMouseEnter={() => setHoveredNodeId(node.id)}
+              onMouseLeave={() => setHoveredNodeId(null)}
+              className="transition-opacity duration-200 cursor-pointer"
+              style={{ opacity }}
+            >
+              <title>{`Сектор: ${node.label}\nОрганизаций: ${node.orgCount}`}</title>
+              <circle r={Math.max(10, Number(node.size) || 10)} className={`fill-sector-${node.color}`} />
+              <text
+                textAnchor="middle"
+                dy={(node.size || 10) + 12}
+                className="text-xs font-medium pointer-events-none fill-foreground"
+              >
+                {node.label}
+              </text>
+            </g>
+          );
+        })}
+      </svg>
+    </div>
+  );
+};
+
+export default React.memo(EconomicGraph);

bugulma/frontend/components/admin/OrganizationTable.tsx

@@ -0,0 +1,195 @@
+import Badge from '@/components/ui/Badge.tsx';
+import Button from '@/components/ui/Button.tsx';
+import Input from '@/components/ui/Input.tsx';
+import VerifiedBadge from '@/components/ui/VerifiedBadge.tsx';
+import { getSectorDisplay } from '@/constants.tsx';
+import { useOrganizationTable } from '@/hooks/features/useOrganizationTable.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import {
+  getTranslatedSectorName
+} from '@/lib/sector-mapper.ts';
+import { getOrganizationSubtypeLabel } from '@/schemas/organizationSubtype.ts';
+import { Organization } from '@/types.ts';
+import React, { useCallback } from 'react';
+
+interface OrganizationTableProps {
+  onUpdateOrganization: (org: Organization) => void;
+}
+
+const VerifyButton = React.memo(
+  ({ org, onVerify }: { org: Organization; onVerify: (org: Organization) => void }) => {
+    const { t } = useTranslation();
+    const handleClick = useCallback(() => {
+      onVerify(org);
+    }, [onVerify, org]);
+
+    return (
+      <Button variant="ghost" size="sm" onClick={handleClick}>
+        {org.Verified ? t('adminPage.orgTable.unverify') : t('adminPage.orgTable.verify')}
+      </Button>
+    );
+  }
+);
+VerifyButton.displayName = 'VerifyButton';
+
+const OrganizationTable = ({ onUpdateOrganization }: OrganizationTableProps) => {
+  const { t } = useTranslation();
+  const { filter, setFilter, searchTerm, setSearchTerm, filteredOrgs } = useOrganizationTable();
+
+  const handleVerify = useCallback(
+    (org: Organization) => {
+      onUpdateOrganization({ ...org, Verified: !org.Verified });
+    },
+    [onUpdateOrganization]
+  );
+
+  return (
+    <div className="space-y-4">
+      <div className="flex flex-col sm:flex-row gap-4">
+        <Input
+          placeholder={t('adminPage.orgTable.searchPlaceholder')}
+          value={searchTerm}
+          onChange={(e) => setSearchTerm(e.target.value)}
+          className="max-w-xs"
+        />
+        <div className="flex items-center gap-2">
+          <Button
+            variant={filter === 'all' ? 'primary' : 'outline'}
+            onClick={() => setFilter('all')}
+          >
+            {t('adminPage.orgTable.filters.all')}
+          </Button>
+          <Button
+            variant={filter === 'verified' ? 'primary' : 'outline'}
+            onClick={() => setFilter('verified')}
+          >
+            {t('adminPage.orgTable.filters.verified')}
+          </Button>
+          <Button
+            variant={filter === 'unverified' ? 'primary' : 'outline'}
+            onClick={() => setFilter('unverified')}
+          >
+            {t('adminPage.orgTable.filters.unverified')}
+          </Button>
+        </div>
+      </div>
+      <div className="border rounded-lg overflow-hidden">
+        <table className="min-w-full divide-y divide-border">
+          <thead className="bg-muted/50">
+            <tr>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.logo')}
+              </th>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.name')}
+              </th>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.sector')}
+              </th>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.type')}
+              </th>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.needsOffers')}
+              </th>
+              <th
+                scope="col"
+                className="px-6 py-3 text-left text-xs font-medium text-muted-foreground uppercase tracking-wider"
+              >
+                {t('adminPage.orgTable.status')}
+              </th>
+              <th scope="col" className="relative px-6 py-3">
+                <span className="sr-only">{t('adminPage.orgTable.action')}</span>
+              </th>
+            </tr>
+          </thead>
+          <tbody className="bg-background divide-y divide-border">
+            {filteredOrgs.map((org) => {
+              // Get sector display information
+              const orgSector = org.Sector || '';
+              const sectorDisplay = getSectorDisplay(orgSector);
+              return (
+                <tr key={org.ID}>
+                  <td className="px-6 py-4">
+                    <div className="h-10 w-10 rounded-md flex items-center justify-center shrink-0 bg-muted overflow-hidden border">
+                      {org.LogoURL ? (
+                        <img
+                          src={org.LogoURL}
+                          alt={`${org.Name} logo`}
+                          className="w-full h-full object-cover"
+                          loading="lazy"
+                          decoding="async"
+                          onError={(e) => {
+                            (e.target as HTMLImageElement).style.display = 'none';
+                          }}
+                        />
+                      ) : (
+                        <div
+                          className={`w-full h-full flex items-center justify-center bg-sector-${sectorDisplay.colorKey}`}
+                        >
+                          {React.cloneElement(sectorDisplay.icon, {
+                            className: 'h-5 w-5 text-primary-foreground',
+                          })}
+                        </div>
+                      )}
+                    </div>
+                  </td>
+                  <td className="px-6 py-4 whitespace-nowrap text-sm font-medium">{org.Name}</td>
+                  <td className="px-6 py-4 whitespace-nowrap text-sm text-muted-foreground">
+                    {getTranslatedSectorName(orgSector, t)}
+                  </td>
+                  <td className="px-6 py-4 whitespace-nowrap text-sm text-muted-foreground">
+                    {org.Subtype ? (
+                      <Badge variant="secondary" className="text-xs">
+                        {getOrganizationSubtypeLabel(org.Subtype)}
+                      </Badge>
+                    ) : (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </td>
+                  <td className="px-6 py-4 whitespace-nowrap text-sm text-muted-foreground">
+                    <div title="Resource flow data will be available when backend API supports counting organization resources">
+                      {t('adminPage.orgTable.notAvailable')}
+                    </div>
+                  </td>
+                  <td className="px-6 py-4 whitespace-nowrap text-sm">
+                    {org.Verified ? (
+                      <VerifiedBadge />
+                    ) : (
+                      <Badge
+                        variant="outline"
+                        className="border-destructive/30 bg-destructive/10 text-destructive"
+                      >
+                        {t('adminPage.orgTable.unverified')}
+                      </Badge>
+                    )}
+                  </td>
+                  <td className="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
+                    <VerifyButton org={org} onVerify={handleVerify} />
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+export default React.memo(OrganizationTable);

bugulma/frontend/components/admin/StatCard.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/Card.tsx';
+
+interface StatCardProps {
+  title: string;
+  value: string;
+  icon: React.ReactNode;
+  subtext?: string;
+}
+
+const StatCard = ({ title, value, icon, subtext }: StatCardProps) => (
+  <Card>
+    <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
+      <CardTitle className="text-sm font-medium text-muted-foreground">{title}</CardTitle>
+      {icon}
+    </CardHeader>
+    <CardContent>
+      <div className="text-2xl font-bold">{value}</div>
+      {subtext && <p className="text-xs text-muted-foreground">{subtext}</p>}
+    </CardContent>
+  </Card>
+);
+
+export default React.memo(StatCard);

bugulma/frontend/components/admin/SupplyChainAnalysis.tsx

@@ -0,0 +1,63 @@
+import React, { useMemo } from 'react';
+import { useSupplyDemandAnalysis } from '@/hooks/api/useAnalyticsAPI.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import type { ItemCount } from '@/services/analytics-api.ts';
+
+const SupplyChainAnalysis = () => {
+  const { t } = useTranslation();
+  const { data: supplyDemand } = useSupplyDemandAnalysis();
+
+  // Helper function to render resource list
+  const ResourceList = React.memo(
+    ({ title, data, barColor }: { title: string; data: ItemCount[]; barColor: string }) => {
+      // Memoize maxValue calculation
+      const maxValue = useMemo(() => (data.length > 0 ? data[0].count : 0), [data]);
+
+      return (
+        <div>
+          <h3 className="text-base font-semibold mb-2">{title}</h3>
+          {data.length > 0 ? (
+            <ul className="space-y-3">
+              {data.map(({ item, count }) => (
+                <li key={item}>
+                  <div className="flex justify-between items-center text-sm mb-1">
+                    <span className="truncate pr-2">{item}</span>
+                    <span className="font-medium text-muted-foreground">{count}</span>
+                  </div>
+                  <div className="w-full bg-muted rounded-full h-1.5">
+                    <div
+                      className={`${barColor} h-1.5 rounded-full`}
+                      style={{ width: `${(count / maxValue) * 100}%` }}
+                    />
+                  </div>
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="text-sm text-muted-foreground">{t('heritage.noData')}</p>
+          )}
+        </div>
+      );
+    }
+  );
+  ResourceList.displayName = 'ResourceList';
+
+  // Memoize arrays to prevent recreation
+  const topNeeds = useMemo(
+    () => (Array.isArray(supplyDemand?.top_needs) ? supplyDemand.top_needs : []),
+    [supplyDemand?.top_needs]
+  );
+  const topOffers = useMemo(
+    () => (Array.isArray(supplyDemand?.top_offers) ? supplyDemand.top_offers : []),
+    [supplyDemand?.top_offers]
+  );
+
+  return (
+    <div className="space-y-6">
+      <ResourceList title={t('adminPage.topNeeds')} data={topNeeds} barColor="bg-destructive" />
+      <ResourceList title={t('adminPage.topOffers')} data={topOffers} barColor="bg-success" />
+    </div>
+  );
+};
+
+export default React.memo(SupplyChainAnalysis);

bugulma/frontend/components/auth/ProtectedRoute.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { Navigate, useLocation } from 'react-router-dom';
+import { useAuth } from '@/contexts/AuthContext';
+
+interface ProtectedRouteProps {
+  children: React.ReactNode;
+  requiredRole?: 'admin' | 'user';
+}
+
+const ProtectedRoute = ({ children, requiredRole = 'user' }: ProtectedRouteProps) => {
+  const { isAuthenticated, user, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return (
+      <div className="flex h-screen w-full items-center justify-center bg-background">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+      </div>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" state={{ from: location }} replace />;
+  }
+
+  if (requiredRole === 'admin' && user?.role !== 'admin') {
+    return <Navigate to="/" replace />;
+  }
+
+  return <>{children}</>;
+};
+
+export default ProtectedRoute;

bugulma/frontend/components/chatbot/ChatHistory.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { ChatMessage } from '@/types.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import TypingIndicator from '@/components/chatbot/TypingIndicator.tsx';
+import MarkdownRenderer from '@/components/chatbot/MarkdownRenderer.tsx';
+import Button from '@/components/ui/Button.tsx';
+import { Check, Copy } from 'lucide-react';
+
+interface ChatHistoryProps {
+  messages: ChatMessage[];
+  messagesEndRef: React.RefObject<HTMLDivElement>;
+  copiedText: string | null;
+  onCopy: (text: string) => void;
+}
+
+const ChatHistory = ({ messages, messagesEndRef, copiedText, onCopy }: ChatHistoryProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className="flex-1 p-4 overflow-y-auto space-y-4">
+      {messages.map((msg) => (
+        <div
+          key={msg.id}
+          className={`flex items-end gap-2 group ${msg.role === 'user' ? 'justify-end' : ''}`}
+        >
+          {msg.role === 'model' && (
+            <div className="h-8 w-8 rounded-full bg-primary text-primary-foreground flex items-center justify-center font-bold text-sm shrink-0 self-start">
+              {t('chatbot.aiAcronym')}
+            </div>
+          )}
+          <div
+            className={`max-w-[calc(100%-3rem)] p-3 rounded-2xl ${msg.role === 'user' ? 'bg-primary text-primary-foreground rounded-br-none' : 'bg-muted rounded-bl-none'}`}
+          >
+            {msg.imageUrl && (
+              <div className="mb-2 rounded-lg overflow-hidden border">
+                <img
+                  src={msg.imageUrl}
+                  alt="Chat image"
+                  className="max-w-full h-auto"
+                  loading="lazy"
+                  decoding="async"
+                  onError={(e) => {
+                    (e.target as HTMLImageElement).style.display = 'none';
+                  }}
+                />
+              </div>
+            )}
+            {msg.isLoading ? <TypingIndicator /> : <MarkdownRenderer text={msg.text} />}
+          </div>
+          {msg.role === 'model' && !msg.isLoading && msg.text && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="p-1.5 h-7 w-7 opacity-0 group-hover:opacity-100 transition-opacity"
+              onClick={() => onCopy(msg.text)}
+              aria-label={t('chatbot.copyLabel')}
+            >
+              {copiedText === msg.text ? (
+                <Check className="h-4 text-current text-success w-4" />
+              ) : (
+                <Copy className="h-4 text-current w-4" />
+              )}
+            </Button>
+          )}
+        </div>
+      ))}
+      <div ref={messagesEndRef} />
+    </div>
+  );
+};
+
+export default React.memo(ChatHistory);

bugulma/frontend/components/chatbot/ChatInput.tsx

@@ -0,0 +1,129 @@
+import React, { useCallback } from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { Mic, Paperclip, Send, X } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+
+interface ChatInputProps {
+  inputValue: string;
+  onInputChange: (value: string) => void;
+  onSendMessage: () => void;
+  attachedImage: { previewUrl: string } | null;
+  onClearAttachment: () => void;
+  onFileChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  fileInputRef: React.RefObject<HTMLInputElement>;
+  inputRef: React.RefObject<HTMLInputElement>;
+  isListening: boolean;
+  onStartListening: () => void;
+  onStopListening: () => void;
+  isSpeechSupported: boolean;
+  isLoading: boolean;
+}
+
+const ChatInput = ({
+  inputValue,
+  onInputChange,
+  onSendMessage,
+  attachedImage,
+  onClearAttachment,
+  onFileChange,
+  fileInputRef,
+  inputRef,
+  isListening,
+  onStartListening,
+  onStopListening,
+  isSpeechSupported,
+  isLoading,
+}: ChatInputProps) => {
+  const { t } = useTranslation();
+
+  const handleSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      onSendMessage();
+    },
+    [onSendMessage]
+  );
+
+  return (
+    <div className="p-3 border-t shrink-0 space-y-2">
+      {attachedImage && (
+        <div className="relative w-20 h-20 rounded-lg overflow-hidden border">
+          <img
+            src={attachedImage.previewUrl}
+            alt="Preview"
+            className="w-full h-full object-cover"
+            loading="eager"
+            decoding="sync"
+          />
+          <Button
+            variant="ghost"
+            size="sm"
+            className="absolute top-1 right-1 h-6 w-6 p-1 rounded-full bg-background/50 hover:bg-background/80"
+            onClick={onClearAttachment}
+            aria-label={t('chatbot.removeImageLabel')}
+          >
+            <X className="h-3 h-4 text-current w-3 w-4" />
+          </Button>
+        </div>
+      )}
+      <form onSubmit={handleSubmit} className="relative flex items-center gap-2">
+        <input
+          ref={fileInputRef}
+          type="file"
+          id="chatbot-file-input"
+          name="chatbot-file-input"
+          onChange={onFileChange}
+          className="hidden"
+          accept="image/*"
+        />
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className="p-2 h-9 w-9 shrink-0"
+          onClick={() => fileInputRef.current?.click()}
+          aria-label={t('chatbot.attachFileLabel')}
+        >
+          <Paperclip className="h-4 text-current w-4" />
+        </Button>
+        <input
+          ref={inputRef}
+          type="text"
+          id="chatbot-message-input"
+          name="chatbot-message-input"
+          value={inputValue}
+          onChange={(e) => onInputChange(e.target.value)}
+          placeholder={t('chatbot.placeholder')}
+          className="w-full h-10 rounded-md border bg-muted pl-4 pr-10 text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          disabled={isLoading}
+        />
+        <div className="flex items-center absolute right-2 top-1/2 -translate-y-1/2">
+          {isSpeechSupported && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className="p-1.5"
+              onClick={isListening ? onStopListening : onStartListening}
+              aria-label={isListening ? t('chatbot.stopRecordLabel') : t('chatbot.recordLabel')}
+            >
+              <Mic className={`h-4 w-4 ${isListening ? 'text-destructive animate-pulse' : ''}`} />
+            </Button>
+          )}
+          <Button
+            type="submit"
+            variant="ghost"
+            size="sm"
+            disabled={isLoading || (!inputValue.trim() && !attachedImage)}
+            className="p-1.5 text-primary disabled:text-muted-foreground"
+            aria-label={t('chatbot.sendLabel')}
+          >
+            <Send className="h-4 text-current w-4" />
+          </Button>
+        </div>
+      </form>
+    </div>
+  );
+};
+
+export default React.memo(ChatInput);

bugulma/frontend/components/chatbot/Chatbot.tsx

@@ -0,0 +1,171 @@
+import { AnimatePresence, motion } from 'framer-motion';
+import { useCallback, useMemo, useState } from 'react';
+import { useChatbot } from '@/hooks/features/useChatbot.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { MessageSquare, Trash2, X } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+import ChatHistory from '@/components/chatbot/ChatHistory.tsx';
+import ChatInput from '@/components/chatbot/ChatInput.tsx';
+
+const useCopyToClipboard = () => {
+  const [copiedText, setCopiedText] = useState<string | null>(null);
+
+  const copy = useCallback(async (text: string) => {
+    if (!navigator?.clipboard) {
+      console.warn('Clipboard not supported');
+      return false;
+    }
+
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopiedText(text);
+      setTimeout(() => setCopiedText(null), 2000);
+      return true;
+    } catch (error) {
+      console.warn('Copy failed', error);
+      setCopiedText(null);
+      return false;
+    }
+  }, []);
+
+  return { copiedText, copy };
+};
+
+const Chatbot = () => {
+  const { t } = useTranslation();
+  const chatbot = useChatbot();
+  const { copiedText, copy } = useCopyToClipboard();
+
+  // Memoize suggested prompts to prevent recreation
+  const suggestedPrompts = useMemo(
+    () => [t('chatbot.prompt1'), t('chatbot.prompt2'), t('chatbot.prompt3')],
+    [t]
+  );
+
+  const handleSuggestionClick = useCallback(
+    (prompt: string) => {
+      chatbot.setInputValue(prompt);
+      chatbot.handleSendMessage();
+    },
+    [chatbot]
+  );
+
+  return (
+    <>
+      <AnimatePresence>
+        {chatbot.isOpen && (
+          <motion.div
+            initial={{ opacity: 0, y: 20, scale: 0.95 }}
+            animate={{ opacity: 1, y: 0, scale: 1 }}
+            exit={{ opacity: 0, y: 20, scale: 0.95 }}
+            transition={{ duration: 0.2, ease: 'easeOut' }}
+            className="fixed bottom-20 right-4 md:right-6 w-[calc(100vw-2rem)] max-w-sm h-[70vh] max-h-[32rem] bg-background rounded-2xl shadow-2xl border flex flex-col z-40"
+          >
+            {/* Header */}
+            <div className="p-4 border-b flex items-center justify-between shrink-0">
+              <div className="flex items-center gap-2">
+                <div className="relative">
+                  <div className="h-8 w-8 rounded-full bg-primary text-primary-foreground flex items-center justify-center font-bold text-sm shrink-0">
+                    {t('chatbot.aiAcronym')}
+                  </div>
+                  <span className="absolute -bottom-0.5 -right-0.5 h-2.5 w-2.5 rounded-full bg-success ring-2 ring-background" />
+                </div>
+                <div>
+                  <h3 className="text-base font-semibold">{t('chatbot.header')}</h3>
+                  <p className="text-xs text-muted-foreground">{t('chatbot.online')}</p>
+                </div>
+              </div>
+              <div>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="p-2 h-8 w-8"
+                  onClick={chatbot.handleClearChat}
+                  aria-label={t('chatbot.clearLabel')}
+                >
+                  <Trash2 className="h-4 text-current w-4" />
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="p-2 h-8 w-8"
+                  onClick={chatbot.toggleChat}
+                  aria-label={t('chatbot.closeLabel')}
+                >
+                  <X className="h-4 text-current w-4" />
+                </Button>
+              </div>
+            </div>
+
+            <ChatHistory
+              messages={chatbot.messages}
+              messagesEndRef={chatbot.messagesEndRef}
+              copiedText={copiedText}
+              onCopy={copy}
+            />
+
+            <div className="p-3 border-t shrink-0 space-y-2">
+              {chatbot.showSuggestions && (
+                <div className="flex flex-wrap gap-2">
+                  {suggestedPrompts.map((prompt, i) => (
+                    <Button
+                      key={i}
+                      variant="outline"
+                      size="sm"
+                      className="text-xs h-auto py-1.5"
+                      onClick={() => handleSuggestionClick(prompt)}
+                    >
+                      {prompt}
+                    </Button>
+                  ))}
+                </div>
+              )}
+              <ChatInput
+                inputValue={chatbot.inputValue}
+                onInputChange={chatbot.setInputValue}
+                onSendMessage={chatbot.handleSendMessage}
+                attachedImage={chatbot.attachedImage}
+                onClearAttachment={() => chatbot.setAttachedImage(null)}
+                onFileChange={chatbot.handleFileChange}
+                fileInputRef={chatbot.fileInputRef}
+                inputRef={chatbot.inputRef}
+                isListening={chatbot.isListening}
+                onStartListening={chatbot.startListening}
+                onStopListening={chatbot.stopListening}
+                isSpeechSupported={chatbot.isSpeechSupported}
+                isLoading={chatbot.isLoading}
+              />
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      <Button
+        variant="primary"
+        size="lg"
+        className="rounded-full h-16 w-16 shadow-lg shadow-primary/30"
+        onClick={chatbot.toggleChat}
+        aria-label={chatbot.isOpen ? t('chatbot.closeLabel') : t('chatbot.openLabel')}
+        aria-expanded={chatbot.isOpen}
+      >
+        <AnimatePresence mode="wait">
+          <motion.div
+            key={chatbot.isOpen ? 'close' : 'chat'}
+            initial={{ opacity: 0, rotate: -30, scale: 0.8 }}
+            animate={{ opacity: 1, rotate: 0, scale: 1 }}
+            exit={{ opacity: 0, rotate: 30, scale: 0.8 }}
+            transition={{ duration: 0.15 }}
+          >
+            {chatbot.isOpen ? (
+              <X className="h-4 h-6 text-current w-4 w-6" />
+            ) : (
+              <MessageSquare className="h-4 h-7 text-current w-4 w-7" />
+            )}
+          </motion.div>
+        </AnimatePresence>
+      </Button>
+    </>
+  );
+};
+
+export default Chatbot;

bugulma/frontend/components/chatbot/MarkdownRenderer.tsx

@@ -0,0 +1,59 @@
+import React, { useMemo } from 'react';
+
+interface MarkdownRendererProps {
+  text: string;
+}
+
+const MarkdownRenderer = ({ text }: MarkdownRendererProps) => {
+  const content = useMemo(() => {
+    if (!text) return null;
+
+    const blocks = text.split(/(\n{2,})/g);
+
+    return blocks.map((block, i) => {
+      if (/^\s*$/.test(block)) {
+        return null;
+      }
+
+      const lines = block.trim().split('\n');
+      const isList =
+        lines.length > 0 &&
+        lines.every((line) => line.trim().startsWith('* ') || line.trim().startsWith('- '));
+
+      if (isList) {
+        return (
+          <ul key={i} className="list-disc list-outside pl-5 space-y-1 my-2">
+            {lines.map((line, j) => {
+              const lineContent = line.trim().substring(2);
+              const boldRegex = /\*\*(.*?)\*\*/g;
+              const parts = lineContent.split(boldRegex);
+
+              return (
+                <li key={j}>
+                  {parts.map((part, k) => (k % 2 === 1 ? <strong key={k}>{part}</strong> : part))}
+                </li>
+              );
+            })}
+          </ul>
+        );
+      } else {
+        const boldRegex = /\*\*(.*?)\*\*/g;
+        return (
+          <div key={i}>
+            {lines.map((line, j) => (
+              <p key={j} className="[&:not(:first-child)]:mt-2">
+                {line
+                  .split(boldRegex)
+                  .map((part, k) => (k % 2 === 1 ? <strong key={k}>{part}</strong> : part))}
+              </p>
+            ))}
+          </div>
+        );
+      }
+    });
+  }, [text]);
+
+  return <>{content}</>;
+};
+
+export default React.memo(MarkdownRenderer);

bugulma/frontend/components/chatbot/TypingIndicator.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+
+const TypingIndicator = () => (
+  <div className="flex items-center gap-1.5 p-2">
+    <span className="h-2 w-2 bg-current rounded-full animate-pulse [animation-delay:-0.3s]"></span>
+    <span className="h-2 w-2 bg-current rounded-full animate-pulse [animation-delay:-0.15s]"></span>
+    <span className="h-2 w-2 bg-current rounded-full animate-pulse"></span>
+  </div>
+);
+
+export default React.memo(TypingIndicator);

bugulma/frontend/components/contact/ContactCard.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import { Card, CardContent } from '@/components/ui/Card.tsx';
+import IconWrapper from '@/components/ui/IconWrapper.tsx';
+
+interface ContactCardProps {
+  icon: React.ReactNode;
+  title: string;
+  children?: React.ReactNode;
+}
+
+const ContactCard = ({ icon, title, children }: ContactCardProps) => {
+  return (
+    <Card className="text-center shadow-md transition-all duration-300 hover:shadow-lg hover:-translate-y-1">
+      <CardContent className="p-8">
+        <IconWrapper>{icon}</IconWrapper>
+        <h3 className="text-xl font-semibold text-foreground mb-2">{title}</h3>
+        <div className="text-base text-muted-foreground">{children}</div>
+      </CardContent>
+    </Card>
+  );
+};
+
+export default ContactCard;

bugulma/frontend/components/form/DynamicFieldArray.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import { useFieldArray, Control, FieldErrors, FieldValues, Path } from 'react-hook-form';
+import Button from '@/components/ui/Button.tsx';
+
+interface DynamicFieldArrayProps<T extends FieldValues> {
+  control: Control<T>;
+  name: Path<T>;
+  title: string;
+  addText: string;
+  errors: FieldErrors<T>;
+  defaultItem: Record<string, unknown>;
+  children?: (index: number) => React.ReactNode;
+}
+
+const DynamicFieldArray = <T extends FieldValues>({
+  control,
+  name,
+  title,
+  addText,
+  errors,
+  defaultItem,
+  children,
+}: DynamicFieldArrayProps<T>) => {
+  const { fields, append, remove } = useFieldArray({ control, name });
+  const arrayErrors = errors[name as string];
+
+  return (
+    <div>
+      <h3 className="text-base font-semibold mb-2">{title}</h3>
+      <div className="space-y-3">
+        {fields.map((field, index) => (
+          <div key={field.id} className="flex items-start gap-2">
+            <div className="flex-1">{children && children(index)}</div>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => remove(index)}
+              className="h-10 w-10 p-0 shrink-0 mt-1.5"
+            >
+              ✕
+            </Button>
+          </div>
+        ))}
+      </div>
+      {arrayErrors && (
+        <p className="text-destructive text-xs mt-1">
+          {(arrayErrors as { message?: string; root?: { message?: string } })?.message ||
+            (arrayErrors as { message?: string; root?: { message?: string } })?.root?.message}
+        </p>
+      )}
+      <Button
+        type="button"
+        variant="ghost"
+        onClick={() => append(defaultItem)}
+        className="text-sm mt-2"
+      >
+        {addText}
+      </Button>
+    </div>
+  );
+};
+
+export default DynamicFieldArray;

bugulma/frontend/components/form/FormField.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import { Control, Controller, FieldErrors, FieldValues, Path } from 'react-hook-form';
+import { spacing } from '@/lib/spacing';
+
+interface FormFieldProps<T extends FieldValues> {
+  control: Control<T>;
+  errors: FieldErrors<T>;
+  name: Path<T>;
+  label: string;
+  description?: string | React.ReactNode;
+  required?: boolean;
+  component: React.ElementType;
+  [key: string]: unknown;
+}
+
+const get = (obj: Record<string, unknown>, path: string) => {
+  return path.split('.').reduce((acc, part) => acc && acc[part], obj);
+};
+
+const FormField = <T extends FieldValues>({
+  control,
+  errors,
+  name,
+  label,
+  description,
+  required,
+  component: Component,
+  ...props
+}: FormFieldProps<T>) => {
+  const error = get(errors, name);
+
+  return (
+    <div className={spacing.formField}>
+      <label htmlFor={name} className="text-sm font-medium">
+        {label}
+        {required && <span className="text-destructive">*</span>}
+      </label>
+      {description && (
+        <p id={`${name}-description`} className="text-xs text-muted-foreground">
+          {description}
+        </p>
+      )}
+      <Controller
+        name={name}
+        control={control}
+        render={({ field }) => {
+          const describedBy = [
+            description ? `${name}-description` : undefined,
+            error ? `${name}-error` : undefined,
+          ]
+            .filter(Boolean)
+            .join(' ');
+
+          return (
+            <Component
+              {...field}
+              {...props}
+              id={name}
+              aria-invalid={!!error}
+              aria-describedby={describedBy.length > 0 ? describedBy : undefined}
+            />
+          );
+        }}
+      />
+      {error && (
+        <p id={`${name}-error`} className="text-destructive text-xs mt-1">
+          {String(error.message)}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export default FormField;

bugulma/frontend/components/heritage/HeritageBuildingCard.tsx

@@ -0,0 +1,189 @@
+import { motion } from 'framer-motion';
+import {
+  Building2,
+  Calendar,
+  ChevronRight,
+  Eye,
+  FileText,
+  MapPin,
+  Palette,
+  Ruler,
+  User,
+} from 'lucide-react';
+import React, { useState } from 'react';
+import Badge from '@/components/ui/Badge.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { BackendHeritageSite } from '@/schemas/backend/heritage-sites';
+
+interface HeritageBuildingCardProps {
+  building: BackendHeritageSite;
+  index: number;
+  onViewDetails?: (building: BackendHeritageSite) => void;
+}
+
+const HeritageBuildingCard: React.FC<HeritageBuildingCardProps> = ({
+  building,
+  index,
+  onViewDetails,
+}) => {
+  const [isHovered, setIsHovered] = useState(false);
+  const { t } = useTranslation();
+
+  const cardVariants = {
+    hidden: { opacity: 0, y: 20 },
+    visible: {
+      opacity: 1,
+      y: 0,
+      transition: {
+        duration: 0.4,
+        delay: index * 0.1,
+      },
+    },
+  };
+
+  const getHeritageStatusVariant = (status?: string): 'protected' | 'cultural-heritage' | 'historical' | 'outline' => {
+    if (!status) return 'outline';
+    switch (status.toLowerCase()) {
+      case 'protected':
+      case 'охраняемый':
+        return 'protected';
+      case 'cultural heritage':
+      case 'памятник культуры':
+        return 'cultural-heritage';
+      case 'historical':
+      case 'исторический':
+        return 'historical';
+      default:
+        return 'outline';
+    }
+  };
+
+  return (
+    <motion.div
+      variants={cardVariants}
+      initial="hidden"
+      whileInView="visible"
+      viewport={{ once: true }}
+      whileHover={{ y: -8 }}
+      onHoverStart={() => setIsHovered(true)}
+      onHoverEnd={() => setIsHovered(false)}
+      className="group relative h-full"
+    >
+      {/* Main Card */}
+      <div className="relative h-full bg-card/80 backdrop-blur-sm border border-border/50 rounded-2xl shadow-lg hover:shadow-2xl transition-all duration-500 overflow-hidden">
+        {/* Decorative gradient overlay */}
+        <div className="absolute inset-0 bg-linear-to-br from-amber-500/5 via-transparent to-amber-600/5 opacity-0 group-hover:opacity-100 transition-opacity duration-500 pointer-events-none" />
+
+        {/* Header Section with Image Placeholder */}
+        <div className="relative h-48 bg-linear-to-br from-amber-50 to-amber-100 dark:from-amber-950/20 dark:to-amber-900/20 flex items-center justify-center">
+          <div className="flex flex-col items-center gap-3 text-amber-600/70">
+            <Building2 className="w-16 h-16" />
+            <span className="text-sm font-medium text-amber-700/60">
+              {t('heritage.architecturalHeritage') || 'Architectural Heritage'}
+            </span>
+          </div>
+
+          {/* Heritage Status Badge */}
+          {building.HeritageStatus && (
+            <div className="absolute top-4 right-4">
+              <Badge variant={getHeritageStatusVariant(building.HeritageStatus)} size="sm">
+                {building.HeritageStatus}
+              </Badge>
+            </div>
+          )}
+        </div>
+
+        {/* Content Section */}
+        <div className="p-6 space-y-4">
+          {/* Title */}
+          <div>
+            <h3 className="text-xl font-serif font-semibold text-foreground group-hover:text-amber-600 transition-colors duration-300 line-clamp-2">
+              {building.Name}
+            </h3>
+          </div>
+
+          {/* Key Information Grid */}
+          <div className="grid grid-cols-2 gap-3">
+            {building.YearBuilt && (
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <Calendar className="w-4 h-4 shrink-0" />
+                <span className="truncate">{building.YearBuilt}</span>
+              </div>
+            )}
+
+            {building.Architect && (
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <User className="w-4 h-4 shrink-0" />
+                <span className="truncate">{building.Architect}</span>
+              </div>
+            )}
+
+            {building.Style && (
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <Palette className="w-4 h-4 shrink-0" />
+                <span className="truncate">{building.Style}</span>
+              </div>
+            )}
+
+            {building.Storeys && (
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <Ruler className="w-4 h-4 shrink-0" />
+                <span>
+                  {building.Storeys} {t('heritage.storeys') || 'storeys'}
+                </span>
+              </div>
+            )}
+          </div>
+
+          {/* Purpose */}
+          {building.OriginalPurpose && (
+            <div className="flex items-start gap-2 text-sm text-muted-foreground">
+              <MapPin className="w-4 h-4 shrink-0 mt-0.5" />
+              <span className="line-clamp-2">{building.OriginalPurpose}</span>
+            </div>
+          )}
+
+          {/* Materials */}
+          {building.Materials && (
+            <div className="flex items-start gap-2 text-sm text-muted-foreground">
+              <Building2 className="w-4 h-4 shrink-0 mt-0.5" />
+              <span className="line-clamp-2">{building.Materials}</span>
+            </div>
+          )}
+
+          {/* Notes */}
+          {building.Notes && (
+            <div className="pt-2 border-t border-border/50">
+              <div className="flex items-start gap-2 text-sm text-muted-foreground">
+                <FileText className="w-4 h-4 shrink-0 mt-0.5" />
+                <span className="line-clamp-3">{building.Notes}</span>
+              </div>
+            </div>
+          )}
+
+          {/* Action Button */}
+          <div className="pt-4 relative z-10">
+            <button
+              onClick={() => onViewDetails?.(building)}
+              className="w-full flex items-center justify-center gap-2 px-4 py-2 bg-amber-500/10 hover:bg-amber-500/20 border border-amber-500/30 hover:border-amber-500/50 rounded-lg text-amber-700 dark:text-amber-300 transition-all duration-300 group/btn"
+            >
+              <Eye className="w-4 h-4" />
+              <span className="font-medium">{t('heritage.viewDetails') || 'View Details'}</span>
+              <ChevronRight className="w-4 h-4 transition-transform group-hover/btn:translate-x-1" />
+            </button>
+          </div>
+        </div>
+
+        {/* Hover Effects */}
+        <motion.div
+          animate={{ opacity: isHovered ? 1 : 0 }}
+          className="absolute inset-0 pointer-events-none"
+        >
+          <div className="absolute inset-0 bg-linear-to-t from-amber-500/5 to-transparent" />
+        </motion.div>
+      </div>
+    </motion.div>
+  );
+};
+
+export default HeritageBuildingCard;

bugulma/frontend/components/heritage/TimelineItem.tsx

@@ -0,0 +1,197 @@
+import IconWrapper from '@/components/ui/IconWrapper.tsx';
+import { HeritageSource, HeritageTimelineItem } from '@/types.ts';
+import { motion, Variants } from 'framer-motion';
+import { Image as ImageIcon, ZoomIn } from 'lucide-react';
+import React, { useCallback, useState } from 'react';
+
+// This utility is now co-located with the component that uses it.
+const parseContent = (
+  text: string,
+  sources?: HeritageSource[]
+): (string | React.ReactElement)[] => {
+  const parts = text.split(/(\*\*.*?\*\*|\[.*?\]\[\d+\])/g).filter(Boolean);
+
+  return parts.map((part, index) => {
+    const boldMatch = part.match(/^\*\*(.*)\*\*$/);
+    if (boldMatch) {
+      return (
+        <strong key={index} className="font-semibold text-foreground">
+          {boldMatch[1]}
+        </strong>
+      );
+    }
+
+    const linkMatch = part.match(/^\[(.*?)\]\[(\d+)\]$/);
+    if (linkMatch && sources) {
+      const linkText = linkMatch[1];
+      const linkIndex = parseInt(linkMatch[2], 10) - 1;
+      if (linkIndex >= 0 && linkIndex < sources.length) {
+        const url = sources[linkIndex].url;
+        return (
+          <a
+            key={index}
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-primary font-semibold hover:underline decoration-2 underline-offset-2 transition-all"
+          >
+            {linkText}
+          </a>
+        );
+      }
+    }
+
+    return part;
+  });
+};
+
+interface TimelineItemProps {
+  item: HeritageTimelineItem;
+  index: number;
+  sources?: HeritageSource[];
+}
+
+const TimelineItem: React.FC<TimelineItemProps> = ({ item, index, sources }) => {
+  const isRightSide = index % 2 !== 0;
+  const [imageLoaded, setImageLoaded] = useState(false);
+  const [imageError, setImageError] = useState(false);
+
+  const contentVariants: Variants = {
+    hidden: { opacity: 0, x: isRightSide ? 50 : -50 },
+    visible: {
+      opacity: 1,
+      x: 0,
+      transition: { duration: 0.6, ease: 'easeOut' },
+    },
+  };
+
+  const imageVariants: Variants = {
+    hidden: { opacity: 0, scale: 1.1 },
+    visible: {
+      opacity: 1,
+      scale: 1,
+      transition: { duration: 0.8, ease: 'easeOut' },
+    },
+  };
+
+  const parsedContent = useCallback(() => {
+    return item.content.split('\n').map((paragraph, pIndex) => (
+      <p key={pIndex} className="mb-3 last:mb-0">
+        {parseContent(paragraph, sources)}
+      </p>
+    ));
+  }, [item.content, sources]);
+
+  return (
+    <motion.div
+      initial="hidden"
+      whileInView="visible"
+      viewport={{ once: true, amount: 0.2 }}
+      variants={contentVariants}
+      className={`relative mb-16 sm:mb-20 flex w-full items-center ${isRightSide ? 'justify-start' : 'justify-end'}`}
+    >
+      <div className={`w-full md:w-5/12 ${isRightSide ? 'md:order-last md:pl-12' : 'md:pr-12'}`}>
+        <motion.div
+          whileHover={{ y: -8, transition: { duration: 0.3 } }}
+          className="group rounded-2xl border-2 border-border/50 bg-card/80 backdrop-blur-sm shadow-lg hover:shadow-2xl hover:border-primary/30 overflow-hidden transition-all duration-300"
+        >
+          {/* Image Section */}
+          {item.imageUrl && !imageError && (
+            <motion.div
+              variants={imageVariants}
+              className="relative w-full h-56 sm:h-64 bg-muted overflow-hidden"
+            >
+              {!imageLoaded && (
+                <div className="absolute inset-0 flex items-center justify-center bg-muted">
+                  <ImageIcon className="w-12 h-12 text-muted-foreground/30 animate-pulse" />
+                </div>
+              )}
+              <img
+                src={item.imageUrl}
+                alt={item.title}
+                className={`w-full h-full object-cover transition-all duration-700 ${
+                  imageLoaded ? 'scale-100 opacity-100' : 'scale-110 opacity-0'
+                } group-hover:scale-105`}
+                loading="lazy"
+                decoding="async"
+                onLoad={() => setImageLoaded(true)}
+                onError={() => setImageError(true)}
+              />
+
+              {/* Image Overlay */}
+              <div className="absolute inset-0 bg-linear-to-t from-black/60 via-transparent to-transparent opacity-0 group-hover:opacity-100 transition-opacity duration-300">
+                <div className="absolute bottom-4 right-4 flex items-center gap-2 text-white text-sm">
+                  <ZoomIn className="w-4 h-4" />
+                  <span className="font-medium">View</span>
+                </div>
+              </div>
+            </motion.div>
+          )}
+
+          {/* Content Section */}
+          <div className="p-6 sm:p-8">
+            {/* Title with decorative line */}
+            <div className="mb-4">
+              <motion.div
+                initial={{ width: 0 }}
+                whileInView={{ width: '3rem' }}
+                viewport={{ once: true }}
+                transition={{ delay: 0.3, duration: 0.6 }}
+                className="h-1 bg-linear-to-r from-primary to-primary/30 rounded-full mb-4"
+              />
+              <h2 className="font-serif text-2xl sm:text-3xl font-semibold text-foreground">
+                {item.title}
+              </h2>
+            </div>
+
+            {/* Content with improved typography */}
+            <div className="prose prose-sm sm:prose-base max-w-none text-muted-foreground">
+              {parsedContent()}
+            </div>
+
+            {/* Decorative bottom accent */}
+            <motion.div
+              initial={{ scaleX: 0 }}
+              whileInView={{ scaleX: 1 }}
+              viewport={{ once: true }}
+              transition={{ delay: 0.5, duration: 0.6 }}
+              className="mt-6 h-px bg-linear-to-r from-transparent via-border to-transparent origin-center"
+            />
+          </div>
+        </motion.div>
+      </div>
+
+      {/* Center Icon with enhanced styling */}
+      <div className="absolute left-1/2 top-1/2 z-10 -translate-x-1/2 -translate-y-1/2">
+        <motion.div
+          initial={{ scale: 0, rotate: -180 }}
+          whileInView={{ scale: 1, rotate: 0 }}
+          viewport={{ once: true }}
+          transition={{ delay: 0.2, type: 'spring', stiffness: 200, damping: 15 }}
+          whileHover={{ scale: 1.15, rotate: 5 }}
+          className="relative"
+        >
+          {/* Background circle to cover the timeline line */}
+          <div className="absolute inset-0 -m-2 rounded-full bg-background" />
+          <IconWrapper className="relative bg-card ring-4 ring-background shadow-xl border-2 border-primary/20">
+            {React.cloneElement(item.icon, {
+              className: 'h-8 w-8 text-primary',
+            })}
+          </IconWrapper>
+        </motion.div>
+      </div>
+
+      {/* Connecting Lines */}
+      <motion.div
+        initial={{ scaleX: 0 }}
+        whileInView={{ scaleX: 1 }}
+        viewport={{ once: true }}
+        transition={{ delay: 0.4, duration: 0.5 }}
+        className={`hidden h-0.5 w-1/12 bg-gradient-to-${isRightSide ? 'l' : 'r'} from-primary/50 to-transparent md:block ${isRightSide ? 'order-2' : ''}`}
+      />
+      <div className={`hidden w-5/12 md:block ${isRightSide ? 'order-1' : ''}`} />
+    </motion.div>
+  );
+};
+
+export default React.memo(TimelineItem);

bugulma/frontend/components/landing/ActivityItem.tsx

@@ -0,0 +1,50 @@
+import React, { useCallback } from 'react';
+import { Organization, LiveActivity as LiveActivityType } from '@/types.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+
+type ActivityWithOrg = LiveActivityType & { org: Organization };
+
+interface ActivityItemProps {
+  activity: ActivityWithOrg;
+  onViewOrganization: (org: Organization) => void;
+  isLastItem: boolean;
+}
+
+const ActivityItem: React.FC<ActivityItemProps> = ({
+  activity,
+  onViewOrganization,
+  isLastItem,
+}) => {
+  const { t } = useTranslation();
+
+  const handleClick = useCallback(() => {
+    onViewOrganization(activity.org);
+  }, [onViewOrganization, activity.org]);
+
+  return (
+    <div className="relative pl-16 py-4">
+      {!isLastItem && (
+        <span className="absolute left-6 top-6 -ml-px h-full w-0.5 bg-border" aria-hidden="true" />
+      )}
+      <div className="relative flex items-center gap-4">
+        <div className="absolute left-0 top-1/2 -translate-y-1/2 z-10 flex h-12 w-12 flex-none items-center justify-center rounded-full bg-background ring-2">
+          {React.cloneElement(activity.icon, { className: 'h-6 w-6 text-primary' })}
+        </div>
+        <div
+          onClick={handleClick}
+          className="flex-auto rounded-lg p-4 cursor-pointer bg-background/50 border border-transparent hover:bg-background transition-all shadow-sm hover:shadow-lg"
+        >
+          <p className="text-base text-foreground">
+            <span className="font-semibold">{activity.org.name}</span> {t(activity.actionKey)}{' '}
+            {activity.subjectKey && <span className="font-semibold">{t(activity.subjectKey)}</span>}
+          </p>
+          <p className="text-sm text-muted-foreground">
+            {t(activity.timeKey, { count: activity.timeValue })}
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default React.memo(ActivityItem);

bugulma/frontend/components/landing/ActivityItemSkeleton.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import Skeleton from '@/components/ui/Skeleton.tsx';
+
+// FIX: Use React.FC to correctly type the component and allow for React's `key` prop.
+const ActivityItemSkeleton: React.FC<{ isLastItem: boolean }> = ({ isLastItem }) => (
+  <div className="relative pl-16 py-4">
+    {!isLastItem && (
+      <span className="absolute left-6 top-6 -ml-px h-full w-0.5 bg-border/50" aria-hidden="true" />
+    )}
+    <div className="relative flex items-center gap-4">
+      <div className="absolute left-0 top-1/2 -translate-y-1/2 z-10 flex h-12 w-12 flex-none items-center justify-center rounded-full bg-background ring-2">
+        <Skeleton className="h-12 w-12 rounded-full" />
+      </div>
+      <div className="flex-auto rounded-lg p-4 bg-background/50 border border-transparent">
+        <Skeleton className="h-4 w-3/4 mb-2" />
+        <Skeleton className="h-3 w-1/4" />
+      </div>
+    </div>
+  </div>
+);
+
+export default ActivityItemSkeleton;

bugulma/frontend/components/landing/AdminPanel.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import Button from '@/components/ui/Button.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+
+interface AdminPanelProps {
+  onNavigateToAdmin: () => void;
+}
+
+const AdminPanel = ({ onNavigateToAdmin }: AdminPanelProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <section
+      className="bg-background min-h-screen flex items-center justify-center scroll-snap-align-start"
+      aria-labelledby="admin-panel-title"
+    >
+      <div className="mx-auto max-w-6xl px-4 py-16 sm:py-24 w-full">
+        <div className="relative rounded-2xl bg-foreground p-8 md:p-12 text-center overflow-hidden">
+          <div
+            className="absolute -top-1/2 -left-1/2 w-[200%] h-[200%] animate-spin-slow"
+            style={{
+              backgroundImage:
+                'radial-gradient(circle at center, hsl(var(--primary) / 0.15), transparent 40%)',
+            }}
+            aria-hidden="true"
+          />
+          <div className="relative z-10 flex flex-col items-center">
+            <h2
+              id="admin-panel-title"
+              className="font-serif text-3xl md:text-4xl font-semibold tracking-tight text-background"
+            >
+              {t('adminPanel.title')}
+            </h2>
+            <p className="text-base md:text-lg text-background/70 mt-4 max-w-2xl mx-auto">
+              {t('adminPanel.subtitle')}
+            </p>
+            <div className="mt-8">
+              <Button
+                size="lg"
+                className="bg-primary hover:bg-primary/90 text-primary-foreground shadow-lg"
+                onClick={onNavigateToAdmin}
+              >
+                {t('adminPanel.ctaButton')}
+              </Button>
+              <p className="text-sm text-background/50 mt-3 max-w-xs mx-auto">
+                {t('adminPanel.ctaNote')}
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};
+
+export default React.memo(AdminPanel);

bugulma/frontend/components/landing/DemoCard.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+const DemoCard = ({
+  icon,
+  sector,
+  item,
+  type,
+}: {
+  icon: React.ReactElement<{ className?: string }>;
+  sector: string;
+  item: string;
+  type: 'Offer' | 'Need';
+}) => (
+  <div className="relative w-full sm:w-5/12 p-6 rounded-xl bg-card border shadow-md text-center">
+    <div className="absolute -top-3 left-1/2 -translate-x-1/2 px-3 py-1 bg-primary text-primary-foreground text-xs font-semibold rounded-full">
+      {type}
+    </div>
+    <div className="h-16 w-16 mb-4 mx-auto rounded-full flex items-center justify-center bg-muted">
+      {React.cloneElement(icon, { className: 'h-8 w-8 text-primary' })}
+    </div>
+    <p className="font-semibold text-lg">{item}</p>
+    <p className="text-sm text-muted-foreground">{sector}</p>
+  </div>
+);
+
+export default React.memo(DemoCard);

bugulma/frontend/components/landing/HeritageSection.tsx

@@ -0,0 +1,69 @@
+import Button from '@/components/ui/Button.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import React from 'react';
+
+interface HeritageSectionProps {
+  onNavigate: () => void;
+}
+
+const HeritageSection = ({ onNavigate }: HeritageSectionProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <section
+      className="relative bg-background min-h-screen flex items-center justify-center scroll-snap-align-start overflow-hidden"
+      aria-labelledby="heritage-title"
+      aria-describedby="heritage-description"
+    >
+      {/* Background image */}
+      <div className="absolute inset-0">
+        <img
+          src="/static/images/heritage/section.jpg"
+          alt=""
+          className="w-full h-full object-cover"
+          style={{ minHeight: '100%', minWidth: '100%' }}
+          onError={(e) => {
+            // Fallback: try API path if direct path fails
+            const target = e.target as HTMLImageElement;
+            if (!target.src.includes('/api/')) {
+              target.src = '/api/static/images/heritage/section.jpg';
+            }
+          }}
+          aria-hidden="true"
+        />
+      </div>
+      {/* Gradient overlay for text readability */}
+      <div
+        className="absolute inset-0 bg-gradient-to-t from-background via-background/85 to-background/60"
+        aria-hidden="true"
+        role="presentation"
+      />
+
+      <div className="relative z-10 mx-auto max-w-6xl px-4 py-16 sm:py-24 md:py-32 text-center w-full">
+        <h2
+          id="heritage-title"
+          className="font-serif text-4xl md:text-5xl font-bold tracking-tight text-foreground mb-4 drop-shadow-[0_2px_8px_rgba(0,0,0,0.5)]"
+          style={{ textShadow: '0 2px 12px rgba(0, 0, 0, 0.6), 0 4px 20px rgba(0, 0, 0, 0.4)' }}
+        >
+          {t('hero.heritageTitle')}
+        </h2>
+        <p
+          id="heritage-description"
+          className="text-lg font-medium text-foreground max-w-3xl mx-auto mb-12 drop-shadow-[0_1px_4px_rgba(0,0,0,0.5)]"
+          style={{ textShadow: '0 1px 6px rgba(0, 0, 0, 0.6), 0 2px 12px rgba(0, 0, 0, 0.4)' }}
+        >
+          {t('hero.heritageSubtitle')}
+        </p>
+        <Button
+          size="lg"
+          onClick={onNavigate}
+          className="shadow-2xl shadow-primary/30"
+        >
+          {t('hero.heritageButton')}
+        </Button>
+      </div>
+    </section>
+  );
+};
+
+export default React.memo(HeritageSection);

bugulma/frontend/components/landing/Hero.tsx

@@ -0,0 +1,308 @@
+import ResourceExchangeVisualization from '@/components/landing/ResourceExchangeVisualization.tsx';
+import Badge from '@/components/ui/Badge.tsx';
+import Button from '@/components/ui/Button.tsx';
+import { Container, Grid } from '@/components/ui/layout';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { motion } from 'framer-motion';
+import React from 'react';
+
+interface HeroProps {
+  onNavigateToMap: () => void;
+  onAddOrganizationClick: () => void;
+  addOrgButtonRef: React.Ref<HTMLButtonElement>;
+}
+
+
+const Hero = ({ onNavigateToMap, onAddOrganizationClick, addOrgButtonRef }: HeroProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <section
+      className="relative bg-background isolate overflow-hidden min-h-screen flex items-center scroll-snap-align-start"
+      aria-label={t('hero.title')}
+    >
+      {/* Animated background pattern */}
+      <motion.div
+        className="absolute inset-0 -z-10 opacity-30"
+        style={{
+          backgroundImage: `radial-gradient(hsl(var(--border) / 0.5) 1px, transparent 1px)`,
+          backgroundSize: 'var(--font-size-2xl) var(--font-size-2xl)',
+        }}
+        animate={{
+          backgroundPosition: ['0px 0px', 'var(--font-size-2xl) var(--font-size-2xl)'],
+        }}
+        transition={{
+          duration: 20,
+          ease: 'linear',
+          repeat: Infinity,
+        }}
+      />
+
+      {/* Abstract backlight effect */}
+      <div className="absolute inset-0 overflow-hidden pointer-events-none" style={{ zIndex: 0 }}>
+        {/* Green backlight orb - behind "Connect Your Business" (left/top) */}
+        <motion.div
+          className="absolute rounded-full"
+          style={{
+            width: 'clamp(400px, 50vw, 900px)',
+            height: 'clamp(400px, 50vw, 900px)',
+            background: `radial-gradient(circle, var(--primary) 0%, rgba(46, 125, 50, 0.2) 20%, transparent 60%)`,
+            left: '5%',
+            top: '15%',
+            filter: 'blur(80px)',
+            mixBlendMode: 'screen',
+            opacity: 0.6,
+          }}
+          animate={{
+            x: [-30, 30, -30],
+            y: [-20, 20, -20],
+            scale: [1, 1.05, 1],
+          }}
+          transition={{
+            duration: 15,
+            repeat: Infinity,
+            ease: 'easeInOut',
+          }}
+        />
+
+        {/* Blue backlight orb - behind "Grow Together" (right/bottom) */}
+        <motion.div
+          className="absolute rounded-full"
+          style={{
+            width: 'clamp(400px, 50vw, 900px)',
+            height: 'clamp(400px, 50vw, 900px)',
+            background: `radial-gradient(circle, var(--accent) 0%, rgba(74, 144, 164, 0.2) 20%, transparent 60%)`,
+            right: '10%',
+            top: '45%',
+            filter: 'blur(80px)',
+            mixBlendMode: 'screen',
+            opacity: 0.6,
+          }}
+          animate={{
+            x: [30, -30, 30],
+            y: [-25, 25, -25],
+            scale: [1, 1.05, 1],
+          }}
+          transition={{
+            duration: 18,
+            repeat: Infinity,
+            ease: 'easeInOut',
+            delay: 2,
+          }}
+        />
+      </div>
+
+      {/* Gradient overlay - positioned after backlight */}
+      <div className="absolute inset-x-0 bottom-0 h-1/2 bg-gradient-to-t from-background via-background/50 to-transparent -z-10" />
+
+      {/* Floating particles effect */}
+      <div className="absolute inset-0 -z-10 overflow-hidden">
+        {[...Array(20)].map((_, i) => (
+          <motion.div
+            key={i}
+            className="absolute w-1 h-1 bg-primary/20 rounded-full"
+            style={{
+              left: `${Math.random() * 100}%`,
+              top: `${Math.random() * 100}%`,
+            }}
+            animate={{
+              y: [-20, -100],
+              opacity: [0, 1, 0],
+            }}
+            transition={{
+              duration: Math.random() * 10 + 10,
+              repeat: Infinity,
+              delay: Math.random() * 10,
+              ease: 'easeOut',
+            }}
+          />
+        ))}
+      </div>
+
+      <Container size="xl" className="py-20 sm:py-24 md:py-32 lg:py-40 xl:py-48 2xl:py-56 w-full">
+        <Grid cols={{ md: 1, lg: 2 }} gap={{ md: "2xl", lg: "3xl", xl: "4xl" }} align="center">
+          <div className="text-center lg:text-left relative z-10">
+            <motion.div
+              initial={{ opacity: 0, y: 20 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={{ duration: 0.8, ease: 'easeOut', delay: 0.2 }}
+            >
+              {/* Animated badge */}
+              <div className="mb-6 lg:mb-8 flex justify-center lg:justify-start">
+                <Badge
+                  variant="material"
+                  showDot={true}
+                  dotColor="primary"
+                  textColor="accent"
+                  size="md"
+                  animate={true}
+                >
+                  {t('hero.kicker')}
+                </Badge>
+              </div>
+
+              {/* Main heading with creative 3D effects and color variations */}
+              <motion.h1
+                className="font-serif text-4xl sm:text-5xl md:text-6xl lg:text-7xl xl:text-8xl 2xl:text-9xl font-bold tracking-tight relative"
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                transition={{ duration: 0.8, delay: 0.4 }}
+              >
+                {(() => {
+                  const title = t('hero.title');
+                  // Split title by period to separate "Connect Your Business" and "Grow Together"
+                  const parts = title.split('.').filter(p => p.trim());
+
+                  return parts.map((part, partIndex) => {
+                    const words = part.trim().split(' ');
+                    const isFirstPart = partIndex === 0;
+
+                    return (
+                      <motion.span
+                        key={partIndex}
+                        className="block mb-2 md:mb-3"
+                        initial={{ opacity: 0, y: 20 }}
+                        animate={{ opacity: 1, y: 0 }}
+                        transition={{
+                          duration: 0.6,
+                          delay: 0.6 + partIndex * 0.2,
+                          ease: [0.16, 1, 0.3, 1]
+                        }}
+                      >
+                        <span className="relative inline-block">
+                          {words.map((word, wordIndex) => (
+                            <motion.span
+                              key={wordIndex}
+                              className="inline-block mr-2 md:mr-3 relative"
+                              initial={{ opacity: 0, y: 20 }}
+                              animate={{ opacity: 1, y: 0 }}
+                              transition={{
+                                duration: 0.5,
+                                delay: 0.8 + partIndex * 0.2 + wordIndex * 0.08,
+                                ease: [0.16, 1, 0.3, 1]
+                              }}
+                            >
+                              {/* 3D shadow layers with color - positioned behind */}
+                              <span
+                                className="absolute inset-0 pointer-events-none"
+                                aria-hidden="true"
+                                style={{
+                                  textShadow: isFirstPart
+                                    ? '2px 2px 0px hsl(var(--primary) / 0.4), 4px 4px 0px hsl(var(--primary) / 0.25), 6px 6px 12px hsl(var(--primary) / 0.15), 8px 8px 20px hsl(var(--primary) / 0.1)'
+                                    : '2px 2px 0px hsl(var(--accent) / 0.4), 4px 4px 0px hsl(var(--accent) / 0.25), 6px 6px 12px hsl(var(--accent) / 0.15), 8px 8px 20px hsl(var(--accent) / 0.1)',
+                                  color: 'transparent',
+                                  zIndex: 0,
+                                }}
+                              >
+                                {word}
+                              </span>
+
+                              {/* Main text - solid and visible with colored shadow */}
+                              <span
+                                className={`relative z-10 inline-block ${
+                                  isFirstPart ? 'text-primary' : 'text-accent'
+                                }`}
+                                style={{
+                                  textShadow: isFirstPart
+                                    ? '0 2px 4px hsl(var(--primary) / 0.4), 0 4px 8px hsl(var(--primary) / 0.2), 0 6px 12px hsl(var(--primary) / 0.1)'
+                                    : '0 2px 4px hsl(var(--accent) / 0.4), 0 4px 8px hsl(var(--accent) / 0.2), 0 6px 12px hsl(var(--accent) / 0.1)',
+                                  filter: isFirstPart
+                                    ? 'drop-shadow(0 1px 2px hsl(var(--primary) / 0.3))'
+                                    : 'drop-shadow(0 1px 2px hsl(var(--accent) / 0.3))',
+                                }}
+                              >
+                                {word}
+                              </span>
+
+                              {/* Animated glow effect */}
+                              <motion.span
+                                className="absolute inset-0 blur-2xl -z-10"
+                                aria-hidden="true"
+                                style={{
+                                  background: isFirstPart
+                                    ? 'radial-gradient(circle, hsl(var(--primary) / 0.3), transparent 70%)'
+                                    : 'radial-gradient(circle, hsl(var(--accent) / 0.3), transparent 70%)',
+                                }}
+                                animate={{
+                                  opacity: [0.2, 0.4, 0.2],
+                                  scale: [1, 1.1, 1],
+                                }}
+                                transition={{
+                                  duration: 3 + wordIndex * 0.2,
+                                  repeat: Infinity,
+                                  ease: 'easeInOut',
+                                }}
+                              />
+                            </motion.span>
+                          ))}
+                        </span>
+                      </motion.span>
+                    );
+                  });
+                })()}
+              </motion.h1>
+
+              <motion.p
+                className="mt-6 text-lg md:text-xl lg:text-2xl xl:text-3xl text-muted-foreground max-w-xl xl:max-w-2xl mx-auto lg:mx-0"
+                initial={{ opacity: 0, y: 10 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ duration: 0.8, delay: 1 }}
+              >
+                {t('hero.subtitle')}
+              </motion.p>
+
+              {/* Action buttons */}
+              <div className="mt-10 lg:mt-12 xl:mt-16 flex flex-col sm:flex-row items-center lg:items-start gap-4 lg:gap-6">
+                <motion.div
+                  initial={{ opacity: 0, y: 20 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ duration: 0.6, delay: 1.2, ease: 'easeOut' }}
+                  className="w-full sm:w-auto"
+                >
+                  <Button
+                    onClick={onNavigateToMap}
+                    size="lg"
+                    className="w-full sm:w-auto shadow-lg shadow-primary/30 hover:shadow-xl hover:shadow-primary/40 transition-all duration-200"
+                  >
+                    {t('hero.mapButton')}
+                  </Button>
+                </motion.div>
+
+                <motion.div
+                  initial={{ opacity: 0, y: 20 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ duration: 0.6, delay: 1.4, ease: 'easeOut' }}
+                  className="w-full sm:w-auto"
+                >
+                  <Button
+                    ref={addOrgButtonRef}
+                    onClick={onAddOrganizationClick}
+                    variant="outline"
+                    size="lg"
+                    className="w-full sm:w-auto bg-background/80 backdrop-blur-sm hover:bg-background/90 transition-all duration-200 hover:border-primary/50"
+                  >
+                    {t('hero.addButton')}
+                  </Button>
+                </motion.div>
+              </div>
+            </motion.div>
+          </div>
+
+          {/* Modern sector visualization */}
+          <motion.div
+            className="row-start-1 lg:col-start-2 relative z-10 flex items-center justify-center lg:justify-end"
+            initial={{ opacity: 0, scale: 0.8 }}
+            animate={{ opacity: 1, scale: 1 }}
+            transition={{ duration: 1, delay: 0.8 }}
+          >
+            <div className="w-full max-w-2xl">
+              <ResourceExchangeVisualization maxItems={6} showStats={true} />
+            </div>
+          </motion.div>
+        </Grid>
+      </Container>
+    </section>
+  );
+};
+
+export default React.memo(Hero);

bugulma/frontend/components/landing/HowItWorksSection.tsx

@@ -0,0 +1,153 @@
+import SectionHeader from '@/components/layout/SectionHeader';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/Card';
+import { Container, Flex, Grid, Stack } from '@/components/ui/layout';
+import { useTranslation } from '@/hooks/useI18n';
+import { themeColors } from '@/lib/theme';
+import { Building2, TrendingUp, Users } from 'lucide-react';
+import React from 'react';
+
+const StepIcon = React.memo(({ icon }: { icon: React.ReactNode }) => (
+  <div className="relative">
+    <div
+      className={`h-20 w-20 rounded-full flex items-center justify-center ${themeColors.background.card} ${themeColors.text.primary} ring-4 ring-background shadow-lg`}
+      aria-hidden="true"
+    >
+      <div className="h-14 w-14 rounded-full flex items-center justify-center bg-primary/10">
+        <div className="text-primary">{icon}</div>
+      </div>
+    </div>
+  </div>
+));
+StepIcon.displayName = 'StepIcon';
+
+const BenefitCard = React.memo(({ title, desc }: { title: string; desc: string }) => (
+  <Card className={`${themeColors.background.card} ${themeColors.text.default} shadow-md border h-full transition-all hover:shadow-lg hover:-translate-y-1`}>
+    <CardHeader className="pb-3">
+      <CardTitle className={`font-serif text-lg ${themeColors.text.primary} leading-tight`}>
+        {title}
+      </CardTitle>
+    </CardHeader>
+    <CardContent className="pt-0">
+      <div className={`prose prose-sm max-w-none ${themeColors.text.muted}`}>
+        <p className="mb-0 leading-relaxed">{desc}</p>
+      </div>
+    </CardContent>
+  </Card>
+));
+BenefitCard.displayName = 'BenefitCard';
+
+const Step = React.memo(
+  ({
+    icon,
+    title,
+    text,
+    children,
+    isLast = false,
+  }: {
+    icon: React.ReactNode;
+    title: string;
+    text: string;
+    children?: React.ReactNode;
+    isLast?: boolean;
+  }) => (
+    <Flex direction="row" gap="xl" align="start" className="relative">
+      {/* Left column: Step icon */}
+      <div className="flex-shrink-0 relative">
+        <StepIcon icon={icon} />
+        {/* Vertical connecting line */}
+        {!isLast && (
+          <div
+            className={`absolute left-1/2 top-20 bottom-0 w-0.5 ${themeColors.border.default} opacity-60 -translate-x-1/2`}
+            style={{ height: 'calc(100% + 2rem)' }}
+            aria-hidden="true"
+          />
+        )}
+      </div>
+
+      {/* Right column: Content */}
+      <Stack spacing="md" className="flex-1 min-w-0">
+        <div>
+          <h3 className="font-serif text-2xl md:text-3xl font-semibold text-foreground mb-4 leading-tight">
+            {title}
+          </h3>
+          <div className={`prose prose-lg max-w-none ${themeColors.text.muted}`}>
+            <p className="mb-0 leading-relaxed">{text}</p>
+          </div>
+        </div>
+        {children && <div className="mt-4">{children}</div>}
+      </Stack>
+    </Flex>
+  )
+);
+Step.displayName = 'Step';
+
+const HowItWorksSection = () => {
+  const { t } = useTranslation();
+
+  const stepData = [
+    {
+      icon: <Building2 className="h-6 w-6 text-primary" />,
+      title: t('howItWorksNew.step1.title'),
+      text: t('howItWorksNew.step1.text'),
+    },
+    {
+      icon: <Users className="h-6 w-6 text-primary" />,
+      title: t('howItWorksNew.step2.title'),
+      text: t('howItWorksNew.step2.text'),
+    },
+    {
+      icon: <TrendingUp className="h-6 w-6 text-primary" />,
+      title: t('howItWorksNew.step3.title'),
+      text: t('howItWorksNew.step3.text'),
+      children: (
+        <Grid cols={{ sm: 1, md: 2, lg: 3 }} gap="lg" className="mt-8">
+          <BenefitCard
+            title={t('howItWorksNew.step3.benefit1.title')}
+            desc={t('howItWorksNew.step3.benefit1.desc')}
+          />
+          <BenefitCard
+            title={t('howItWorksNew.step3.benefit2.title')}
+            desc={t('howItWorksNew.step3.benefit2.desc')}
+          />
+          <BenefitCard
+            title={t('howItWorksNew.step3.benefit3.title')}
+            desc={t('howItWorksNew.step3.benefit3.desc')}
+          />
+        </Grid>
+      ),
+    },
+  ];
+
+  return (
+    <section
+      className={`${themeColors.background.muted} min-h-screen flex items-center scroll-snap-align-start`}
+      aria-labelledby="how-it-works-title"
+    >
+      <Container className="py-16 sm:py-24 lg:py-32 w-full">
+        <SectionHeader
+          id="how-it-works-title"
+          title={t('howItWorksNew.title')}
+          subtitle={t('howItWorksNew.subtitle')}
+          className="mb-16 sm:mb-20 lg:mb-24"
+        />
+
+        <Stack spacing="3xl" className="max-w-6xl mx-auto" role="list" aria-label={t('howItWorksNew.title')}>
+          {stepData.map((step, index) => (
+            <li key={index} className="list-none">
+              <Step
+                icon={step.icon}
+                title={step.title}
+                text={step.text}
+                isLast={index === stepData.length - 1}
+              >
+                {step.children}
+              </Step>
+            </li>
+          ))}
+        </Stack>
+      </Container>
+    </section>
+  );
+};
+
+export default React.memo(HowItWorksSection);

bugulma/frontend/components/landing/LiveActivity.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { useLiveActivity } from '@/hooks/features/useLiveActivity.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { Organization } from '@/types.ts';
+import SectionHeader from '@/components/layout/SectionHeader.tsx';
+import { Container, Stack } from '@/components/ui/layout';
+import ActivityItem from '@/components/landing/ActivityItem.tsx';
+import ActivityItemSkeleton from '@/components/landing/ActivityItemSkeleton.tsx';
+
+interface LiveActivityProps {
+  onViewOrganization: (org: Organization) => void;
+  organizations: Organization[];
+}
+
+const LiveActivity = ({ onViewOrganization, organizations }: LiveActivityProps) => {
+  const { t } = useTranslation();
+  const { activitiesWithOrgs, isLoading } = useLiveActivity(organizations);
+
+  // Hide section completely if no activities and not loading
+  if (!isLoading && activitiesWithOrgs.length === 0) {
+    return null;
+  }
+
+  return (
+    <section className="bg-muted/50 scroll-snap-align-start" aria-labelledby="live-activity-title">
+      <Container size="md" className="py-16 sm:py-24 w-full">
+        <SectionHeader
+          id="live-activity-title"
+          title={t('liveActivity.title')}
+          className="mb-10 sm:mb-12"
+        />
+        <div className="flow-root">
+          {isLoading ? (
+            <Stack spacing="none" className="-my-4">
+              {Array.from({ length: 3 }).map((_, index) => (
+                <ActivityItemSkeleton key={index} isLastItem={index === 2} />
+              ))}
+            </Stack>
+          ) : (
+            <Stack spacing="none" className="-my-4">
+              {activitiesWithOrgs.map((activity, index) => (
+                <ActivityItem
+                  key={`${activity.org.id}-${index}`}
+                  activity={activity}
+                  onViewOrganization={onViewOrganization}
+                  isLastItem={index === activitiesWithOrgs.length - 1}
+                />
+              ))}
+            </Stack>
+          )}
+        </div>
+      </Container>
+    </section>
+  );
+};
+
+export default React.memo(LiveActivity);

bugulma/frontend/components/landing/ModernSectorVisualization.tsx

@@ -0,0 +1,104 @@
+import Badge from '@/components/ui/Badge.tsx';
+import { Card } from '@/components/ui/Card.tsx';
+import { Grid } from '@/components/ui/layout';
+import { useDynamicSectors } from '@/hooks/useDynamicSectors.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { motion } from 'framer-motion';
+import React from 'react';
+
+interface ModernSectorVisualizationProps {
+  maxItems?: number;
+  showStats?: boolean;
+}
+
+const ModernSectorVisualization: React.FC<ModernSectorVisualizationProps> = ({
+  maxItems = 8,
+  showStats = false
+}) => {
+  const { t } = useTranslation();
+
+  // Safety check for translation context
+  if (!t) {
+    return (
+      <div className="w-full max-w-4xl mx-auto">
+        <div className="text-center py-8">
+          <p className="text-muted-foreground">Loading...</p>
+        </div>
+      </div>
+    );
+  }
+  const { sectors: dynamicSectors, isLoading } = useDynamicSectors(maxItems);
+
+  if (isLoading) {
+    return (
+      <div className="w-full relative">
+        <Grid cols={{ sm: 2, md: 3 }} gap="md">
+          {Array.from({ length: maxItems }).map((_, i) => (
+            <Card key={i} className="p-6 animate-pulse h-full flex flex-col items-center justify-center">
+              <div className="w-16 h-16 bg-muted rounded-xl mb-4"></div>
+              <div className="w-24 h-4 bg-muted rounded mb-2"></div>
+              <div className="w-20 h-3 bg-muted rounded"></div>
+            </Card>
+          ))}
+        </Grid>
+      </div>
+    );
+  }
+
+  return (
+    <div className="w-full relative">
+      <Grid cols={{ sm: 2, md: 3 }} gap="md" className="relative">
+        {dynamicSectors.slice(0, maxItems).map((sector, index) => (
+          <motion.div
+            key={sector.backendName}
+            initial={{ opacity: 0, y: 20 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{
+              duration: 0.5,
+              delay: index * 0.1,
+              ease: [0.25, 0.46, 0.45, 0.94]
+            }}
+            className="relative"
+          >
+            <Card className="group relative p-6 hover:shadow-lg transition-all duration-300 hover:-translate-y-1 bg-card/50 backdrop-blur-sm border-border/50 h-full flex flex-col">
+              <div className="flex flex-col items-center text-center space-y-4 relative z-10 flex-1">
+                <div className={`flex-shrink-0 w-16 h-16 rounded-xl flex items-center justify-center bg-gradient-to-br from-sector-${sector.colorKey}/20 to-sector-${sector.colorKey}/10 ring-2 ring-sector-${sector.colorKey}/20 group-hover:ring-sector-${sector.colorKey}/40 transition-all duration-300`}>
+                  {React.cloneElement(sector.icon, {
+                    className: `w-8 h-8 text-sector-${sector.colorKey} group-hover:scale-110 transition-transform duration-300`
+                  })}
+                </div>
+
+                <div className="flex-1 min-w-0 w-full">
+                  <h3 className={`font-semibold text-lg text-foreground group-hover:text-sector-${sector.colorKey} transition-colors duration-300`}>
+                    {t(`${sector.nameKey}.name`)}
+                  </h3>
+
+                  {showStats && sector.count !== undefined && (
+                    <div className="flex items-center justify-center mt-3">
+                      <Badge
+                        variant={sector.colorKey as any}
+                        size="sm"
+                        className={
+                          ['construction', 'production', 'recreation', 'logistics'].includes(sector.colorKey)
+                            ? ''
+                            : `bg-sector-${sector.colorKey}/10 text-sector-${sector.colorKey} border-sector-${sector.colorKey}/20`
+                        }
+                      >
+                        {t('common.organizations', { count: sector.count })}
+                      </Badge>
+                    </div>
+                  )}
+                </div>
+              </div>
+
+              {/* Subtle connection indicator */}
+              <div className={`absolute inset-0 rounded-lg bg-gradient-to-br from-transparent via-transparent to-sector-${sector.colorKey}/5 opacity-0 group-hover:opacity-100 transition-opacity duration-300 pointer-events-none`} />
+            </Card>
+          </motion.div>
+        ))}
+      </Grid>
+    </div>
+  );
+};
+
+export default React.memo(ModernSectorVisualization);

bugulma/frontend/components/landing/ResourceExchangeVisualization.tsx

@@ -0,0 +1,780 @@
+import { useDynamicSectors } from '@/hooks/useDynamicSectors.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { motion } from 'framer-motion';
+import { Briefcase, Hammer, Layers, ShoppingBag } from 'lucide-react';
+import React, { useMemo, useState } from 'react';
+
+interface ResourceExchangeVisualizationProps {
+  maxItems?: number;
+  showStats?: boolean;
+}
+
+// Layout constants - single source of truth
+const LAYOUT_CONFIG = {
+  SVG_VIEWBOX_SIZE: 500,
+  CENTER_X: 250,
+  CENTER_Y: 250,
+  SECTOR_RADIUS: 180,
+  RESOURCE_ICON_OFFSET: 45, // Distance from sector center for unidirectional
+  RESOURCE_ICON_SIZE: 7, // Radius in SVG units
+  SECTOR_NODE_RADIUS: 32,
+  SECTOR_ICON_BACKGROUND_RADIUS: 22,
+  CONNECTION_BADGE_OFFSET: 28,
+  CONNECTION_BADGE_RADIUS: 14,
+  LABEL_OFFSET_Y: 55,
+  NODE_RADIUS_FOR_PARTICLES: 35, // Hide particles within this radius
+} as const;
+
+// Layout calculator - handles all coordinate transformations
+// Uses SVG's native coordinate system - no pixel conversion needed
+class LayoutCalculator {
+  private svgSize: number;
+
+  constructor(svgSize: number = LAYOUT_CONFIG.SVG_VIEWBOX_SIZE) {
+    this.svgSize = svgSize;
+  }
+
+  // Calculate sector positions in circular layout (SVG coordinates)
+  calculateSectorPositions(count: number): Array<{ x: number; y: number; angle: number }> {
+    if (count === 0) return [];
+
+    const { CENTER_X, CENTER_Y, SECTOR_RADIUS } = LAYOUT_CONFIG;
+    const angleStep = (2 * Math.PI) / count;
+
+    return Array.from({ length: count }, (_, index) => {
+      const angle = index * angleStep - Math.PI / 2;
+      return {
+        x: CENTER_X + SECTOR_RADIUS * Math.cos(angle),
+        y: CENTER_Y + SECTOR_RADIUS * Math.sin(angle),
+        angle,
+      };
+    });
+  }
+
+  // Calculate resource icon position (SVG coordinates)
+  // Avoids overlapping with connection count badges
+  calculateResourceIconPosition(
+    fromPos: { x: number; y: number },
+    toPos: { x: number; y: number },
+    isBidirectional: boolean,
+    fromIndex: number,
+    toIndex: number,
+    showStats: boolean = false
+  ): { x: number; y: number } {
+    const angle = Math.atan2(toPos.y - fromPos.y, toPos.x - fromPos.x);
+
+    if (isBidirectional) {
+      // Position at midpoint, offset perpendicular
+      // Use from/to indices to ensure consistent side assignment
+      const midpointX = (fromPos.x + toPos.x) / 2;
+      const midpointY = (fromPos.y + toPos.y) / 2;
+      const perpAngle = angle + Math.PI / 2;
+      // Ensure consistent side: lower index → higher index goes left, reverse goes right
+      const sideOffset = fromIndex < toIndex ? -12 : 12;
+      return {
+        x: midpointX + Math.cos(perpAngle) * sideOffset,
+        y: midpointY + Math.sin(perpAngle) * sideOffset,
+      };
+    } else {
+      // Position next to source organization
+      let resourceX = fromPos.x + Math.cos(angle) * LAYOUT_CONFIG.RESOURCE_ICON_OFFSET;
+      let resourceY = fromPos.y + Math.sin(angle) * LAYOUT_CONFIG.RESOURCE_ICON_OFFSET;
+
+      // Check if resource icon would overlap with badge (badge is at +28x, -28y from sector center)
+      if (showStats) {
+        const badgeX = fromPos.x + LAYOUT_CONFIG.CONNECTION_BADGE_OFFSET;
+        const badgeY = fromPos.y - LAYOUT_CONFIG.CONNECTION_BADGE_OFFSET;
+        const badgeRadius = LAYOUT_CONFIG.CONNECTION_BADGE_RADIUS + 8; // Add padding
+        const resourceIconRadius = 14; // Half of foreignObject size (28/2)
+
+        const distanceToBadge = Math.sqrt(
+          Math.pow(resourceX - badgeX, 2) + Math.pow(resourceY - badgeY, 2)
+        );
+
+        // If too close to badge, adjust position
+        if (distanceToBadge < badgeRadius + resourceIconRadius) {
+          // Move resource icon further along the connection direction
+          const adjustedOffset = LAYOUT_CONFIG.RESOURCE_ICON_OFFSET + 20;
+          resourceX = fromPos.x + Math.cos(angle) * adjustedOffset;
+          resourceY = fromPos.y + Math.sin(angle) * adjustedOffset;
+
+          // Also check if still too close, if so offset perpendicularly
+          const newDistanceToBadge = Math.sqrt(
+            Math.pow(resourceX - badgeX, 2) + Math.pow(resourceY - badgeY, 2)
+          );
+
+          if (newDistanceToBadge < badgeRadius + resourceIconRadius) {
+            // Offset perpendicular to avoid badge
+            const perpAngle = angle + Math.PI / 2;
+            const perpOffset = badgeRadius + resourceIconRadius - newDistanceToBadge + 5;
+            // Choose side that's away from badge
+            const badgeAngle = Math.atan2(badgeY - fromPos.y, badgeX - fromPos.x);
+            const angleDiff = angle - badgeAngle;
+            const perpDirection = Math.abs(angleDiff) < Math.PI / 2 ? -1 : 1;
+            resourceX += Math.cos(perpAngle) * perpOffset * perpDirection;
+            resourceY += Math.sin(perpAngle) * perpOffset * perpDirection;
+          }
+        }
+      }
+
+      return {
+        x: resourceX,
+        y: resourceY,
+      };
+    }
+  }
+
+  // Calculate connection line start position (SVG coordinates)
+  calculateConnectionStart(
+    fromPos: { x: number; y: number },
+    resourceIconPos: { x: number; y: number },
+    isBidirectional: boolean
+  ): { x: number; y: number } {
+    if (isBidirectional) {
+      return { x: fromPos.x, y: fromPos.y };
+    } else {
+      const angle = Math.atan2(
+        resourceIconPos.y - fromPos.y,
+        resourceIconPos.x - fromPos.x
+      );
+      return {
+        x: resourceIconPos.x + Math.cos(angle) * LAYOUT_CONFIG.RESOURCE_ICON_SIZE,
+        y: resourceIconPos.y + Math.sin(angle) * LAYOUT_CONFIG.RESOURCE_ICON_SIZE,
+      };
+    }
+  }
+
+  // Get SVG coordinate bounds for foreignObject positioning
+  // Returns position and size in SVG coordinate system
+  getForeignObjectBounds(svgX: number, svgY: number, size: number = 44): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } {
+    // Center the foreignObject on the SVG coordinate
+    return {
+      x: svgX - size / 2,
+      y: svgY - size / 2,
+      width: size,
+      height: size,
+    };
+  }
+
+  // Calculate distance between two points
+  distance(
+    p1: { x: number; y: number },
+    p2: { x: number; y: number }
+  ): number {
+    return Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2));
+  }
+}
+
+// Resource types that can flow between sectors
+const RESOURCE_TYPES = [
+  { type: 'products', icon: ShoppingBag, color: 'text-blue-500' },
+  { type: 'services', icon: Briefcase, color: 'text-purple-500' },
+  { type: 'materials', icon: Layers, color: 'text-green-500' },
+  { type: 'equipment', icon: Hammer, color: 'text-orange-500' },
+] as const;
+
+// Generate potential connections between sectors based on common symbiosis patterns
+// Creates varying connection counts (1-4 connections per sector) for visual interest
+const generateConnections = (sectors: Array<{ backendName?: string; colorKey: string }>) => {
+  const connections: Array<{ from: number; to: number; resourceType: string; strength: number }> = [];
+  // Track resource types used per sector to ensure variety
+  const sectorResourceUsage: Map<number, Set<number>> = new Map();
+
+  if (sectors.length < 2) return connections;
+
+  // Connection pattern per sector index to create varied counts: [1, 2, 3, 2, 4, 3]
+  const connectionPatterns = [
+    [1],           // Sector 0: 1 connection (to next)
+    [1, -Math.floor(sectors.length / 2)], // Sector 1: 2 connections (next + opposite)
+    [1, -1, 2],    // Sector 2: 3 connections (next + prev + skipOne)
+    [1, -Math.floor(sectors.length / 2)], // Sector 3: 2 connections (next + opposite)
+    [1, -1, -Math.floor(sectors.length / 2), 2], // Sector 4: 4 connections
+    [1, -1, 2],    // Sector 5: 3 connections (next + prev + skipOne)
+  ];
+
+  for (let i = 0; i < sectors.length; i++) {
+    const pattern = connectionPatterns[i] || [1]; // Default to 1 connection
+    if (!sectorResourceUsage.has(i)) {
+      sectorResourceUsage.set(i, new Set());
+    }
+
+    pattern.forEach((offset) => {
+      const targetIndex = (i + offset + sectors.length) % sectors.length;
+
+      // Don't connect to self
+      if (targetIndex === i) return;
+
+      // Avoid duplicate connections (check if reverse connection already exists)
+      const reverseExists = connections.some(
+        c => c.from === targetIndex && c.to === i
+      );
+
+      if (!reverseExists) {
+        // Assign resource type ensuring variety - cycle through all resource types globally
+        // This ensures all resource types (products, services, materials, equipment) are used
+        const connectionIndex = connections.length;
+        const resourceTypeIndex = connectionIndex % RESOURCE_TYPES.length;
+
+        // Track usage per sector for reference (but don't restrict assignment)
+        const usedResources = sectorResourceUsage.get(i)!;
+        usedResources.add(resourceTypeIndex);
+
+        connections.push({
+          from: i,
+          to: targetIndex,
+          resourceType: RESOURCE_TYPES[resourceTypeIndex].type,
+          strength: Math.abs(offset) === 1 ? 0.8 : Math.abs(offset) === Math.floor(sectors.length / 2) ? 0.5 : 0.6,
+        });
+      }
+    });
+  }
+
+  return connections;
+};
+
+const ResourceExchangeVisualization: React.FC<ResourceExchangeVisualizationProps> = ({
+  maxItems = 6,
+  showStats = false
+}) => {
+  const { t } = useTranslation();
+  const { sectors: dynamicSectors, isLoading } = useDynamicSectors(maxItems);
+  const [hoveredSector, setHoveredSector] = useState<number | null>(null);
+  const [activeConnections, setActiveConnections] = useState<Set<string>>(new Set());
+
+  // Create layout calculator instance - uses SVG native coordinate system
+  const layoutCalculator = useMemo(
+    () => new LayoutCalculator(LAYOUT_CONFIG.SVG_VIEWBOX_SIZE),
+    []
+  );
+
+  // Generate sector positions using layout calculator
+  const sectorPositions = useMemo(() => {
+    return layoutCalculator.calculateSectorPositions(dynamicSectors.length);
+  }, [dynamicSectors.length, layoutCalculator]);
+
+  // Generate connections between sectors
+  const connections = useMemo(() => {
+    if (dynamicSectors.length === 0) return [];
+    return generateConnections(dynamicSectors);
+  }, [dynamicSectors]);
+
+  // Activate connections on hover
+  React.useEffect(() => {
+    if (hoveredSector !== null) {
+      const active = new Set<string>();
+      connections.forEach((conn, idx) => {
+        if (conn.from === hoveredSector || conn.to === hoveredSector) {
+          active.add(`conn-${idx}`);
+        }
+      });
+      setActiveConnections(active);
+    } else {
+      setActiveConnections(new Set());
+    }
+  }, [hoveredSector, connections]);
+
+  if (isLoading) {
+    return (
+      <div className="w-full relative aspect-square max-w-lg mx-auto">
+        <div className="absolute inset-0 flex items-center justify-center">
+          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary"></div>
+        </div>
+      </div>
+    );
+  }
+
+  if (dynamicSectors.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="w-full flex flex-col items-center gap-4 max-w-lg mx-auto">
+      {/* Title */}
+      <div className="text-center">
+        <h3 className="text-sm font-semibold text-foreground mb-1">
+          Resource Exchange Network
+        </h3>
+        <p className="text-xs text-muted-foreground">
+          Businesses connect to exchange resources
+        </p>
+      </div>
+
+      {/* SVG Canvas for network visualization */}
+      <div className="relative w-full aspect-square min-h-[400px]">
+        <svg
+          viewBox={`0 0 ${LAYOUT_CONFIG.SVG_VIEWBOX_SIZE} ${LAYOUT_CONFIG.SVG_VIEWBOX_SIZE}`}
+          className="w-full h-full"
+          preserveAspectRatio="xMidYMid meet"
+          style={{ overflow: 'visible' }}
+        >
+        <defs>
+          {/* Gradient for connection lines */}
+          <linearGradient id="connectionGradient" x1="0%" y1="0%" x2="100%" y2="0%">
+            <stop offset="0%" stopColor="hsl(var(--primary))" stopOpacity="0.3" />
+            <stop offset="50%" stopColor="hsl(var(--primary))" stopOpacity="0.6" />
+            <stop offset="100%" stopColor="hsl(var(--primary))" stopOpacity="0.3" />
+          </linearGradient>
+
+          {/* Glow filter for active connections */}
+          <filter id="glow">
+            <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+            <feMerge>
+              <feMergeNode in="coloredBlur"/>
+              <feMergeNode in="SourceGraphic"/>
+            </feMerge>
+          </filter>
+        </defs>
+
+        {/* Connection lines (edges) */}
+        <g>
+          {connections.map((conn, idx) => {
+            const fromPos = sectorPositions[conn.from];
+            const toPos = sectorPositions[conn.to];
+            if (!fromPos || !toPos) return null;
+
+            const isActive = activeConnections.has(`conn-${idx}`) || hoveredSector === null;
+
+            // Check if this is a bidirectional exchange (both A→B and B→A exist)
+            const reverseConnection = connections.find(
+              c => c.from === conn.to && c.to === conn.from
+            );
+            const isBidirectional = !!reverseConnection;
+
+            // Calculate resource icon position using layout calculator
+            const resourceIconPos = layoutCalculator.calculateResourceIconPosition(
+              fromPos,
+              toPos,
+              isBidirectional,
+              conn.from,
+              conn.to,
+              showStats
+            );
+
+            // Calculate connection start position
+            const connectionStart = layoutCalculator.calculateConnectionStart(
+              fromPos,
+              resourceIconPos,
+              isBidirectional
+            );
+
+            // Calculate total distance for particle animation
+            const totalDistance = layoutCalculator.distance(connectionStart, toPos);
+
+            return (
+              <g key={`connection-${idx}`}>
+                {/* Connection line - for bidirectional: source to destination (icons at midpoint); for unidirectional: from resource icon to destination */}
+                <motion.line
+                  x1={connectionStart.x}
+                  y1={connectionStart.y}
+                  x2={toPos.x}
+                  y2={toPos.y}
+                  stroke="hsl(var(--primary))"
+                  strokeWidth={isActive ? 2 : 1}
+                  strokeDasharray={isActive ? "0" : "4 4"}
+                  opacity={isActive ? conn.strength : 0.2}
+                  filter={isActive ? "url(#glow)" : undefined}
+                  initial={{ pathLength: 0 }}
+                  animate={{ pathLength: isActive ? 1 : 0.3 }}
+                  transition={{ duration: 1, delay: idx * 0.1 }}
+                />
+
+                {/* Animated resource flow particles - flow from resource icon to organization */}
+                {isActive && totalDistance > 0 && (
+                  <>
+                    {[...Array(3)].map((_, particleIdx) => {
+                      // Particles start exactly at the resource icon position
+                      const particleStartX = resourceIconPos.x;
+                      const particleStartY = resourceIconPos.y;
+
+                      // Particles travel all the way to the organization icon
+                      // Stop just before the organization circle edge to avoid overlap
+                      const organizationRadius = LAYOUT_CONFIG.SECTOR_NODE_RADIUS;
+                      const particleEndX = toPos.x;
+                      const particleEndY = toPos.y;
+
+                      // Calculate full distance from resource icon to organization
+                      const fullDistance = layoutCalculator.distance(
+                        { x: particleStartX, y: particleStartY },
+                        { x: particleEndX, y: particleEndY }
+                      );
+
+                      // Base duration with randomization for organic feel
+                      const baseDuration = 4 + conn.strength * 2;
+                      const randomVariation = 0.7 + Math.random() * 0.6; // 0.7x to 1.3x speed variation
+                      const particleDuration = baseDuration * randomVariation;
+
+                      // Stagger particles for continuous flow - overlap them so there's always a particle visible
+                      // Each particle starts before the previous one finishes (overlap by ~60%)
+                      const overlapRatio = 0.6; // 60% overlap
+                      const staggerDelay = particleIdx * particleDuration * (1 - overlapRatio);
+
+                      // Randomize particle properties for dynamic feel
+                      const particleSize = 2.5 + Math.random() * 1.5; // 2.5-4px radius
+                      const particleOpacity = 0.6 + Math.random() * 0.4; // 0.6-1.0 opacity
+
+                      // Slight path variation for more organic movement (small perpendicular offset)
+                      const pathVariation = (Math.random() - 0.5) * 4; // Reduced to ±2px for more realistic path
+                      const angle = Math.atan2(particleEndY - particleStartY, particleEndX - particleStartX);
+                      const perpAngle = angle + Math.PI / 2;
+                      const offsetX = Math.cos(perpAngle) * pathVariation;
+                      const offsetY = Math.sin(perpAngle) * pathVariation;
+
+                      // Add slight random delay to break synchronization
+                      const randomDelay = Math.random() * 0.5;
+
+                      // Wait for connection line to be visible before starting particles
+                      // Connection line has delay: idx * 0.1 and duration: 1s
+                      const connectionLineDelay = idx * 0.1;
+                      const connectionLineDuration = 1;
+                      const waitForLine = connectionLineDelay + connectionLineDuration * 0.8; // Start particles when line is 80% visible
+
+                      return (
+                        <motion.circle
+                          key={`particle-${idx}-${particleIdx}`}
+                          r={particleSize}
+                          fill="hsl(var(--primary))"
+                          initial={{
+                            cx: particleStartX + offsetX,
+                            cy: particleStartY + offsetY,
+                            opacity: particleOpacity, // Start fully visible
+                          }}
+                          animate={{
+                            cx: [particleStartX + offsetX, particleEndX + offsetX],
+                            cy: [particleStartY + offsetY, particleEndY + offsetY],
+                            opacity: [particleOpacity, particleOpacity, 0], // Stay fully visible, fade out only when reaching destination
+                          }}
+                          transition={{
+                            duration: particleDuration,
+                            repeat: Infinity,
+                            delay: waitForLine + staggerDelay + randomDelay, // Wait for line to appear first
+                            ease: "linear",
+                            times: [0, 0.95, 1], // Fully visible (95%), fade out only at destination (5%)
+                          }}
+                        />
+                      );
+                    })}
+                  </>
+                )}
+
+              </g>
+            );
+          })}
+        </g>
+
+        {/* Sector nodes */}
+        {dynamicSectors.map((sector, index) => {
+          const pos = sectorPositions[index];
+          if (!pos) return null;
+
+          const isHovered = hoveredSector === index;
+          const sectorConnections = connections.filter(
+            c => c.from === index || c.to === index
+          );
+
+          // Find incoming connections (where this sector is the destination)
+          const incomingConnections = connections.filter(c => c.to === index);
+
+          // Calculate pulse animation synchronized with particle arrivals
+          // Particles take (4 + strength * 2) seconds to travel, and we have 3 particles staggered
+          const getPulseProps = () => {
+            // Don't pulse if no incoming connections or if this sector is hovered
+            if (incomingConnections.length === 0 || isHovered) {
+              return {};
+            }
+
+            // Find active incoming connections (where particles are flowing)
+            const activeIncoming = incomingConnections.find((conn) => {
+              const connIdx = connections.findIndex(c => c.from === conn.from && c.to === conn.to);
+              const connKey = `conn-${connIdx}`;
+              // Connection is active if it's in activeConnections set or if nothing is hovered (all connections active)
+              return activeConnections.has(connKey) || hoveredSector === null;
+            });
+
+            if (!activeIncoming) return {};
+
+            // Calculate pulse timing based on continuous particle flow
+            // With 6 particles overlapping at 60%, particles arrive more frequently
+            const baseDuration = 4 + activeIncoming.strength * 2;
+            const overlapRatio = 0.6;
+            const particleInterval = baseDuration * (1 - overlapRatio); // Time between particle arrivals
+            const averageDuration = baseDuration * 0.85; // Average duration accounting for randomization
+
+            // Pulse when particles arrive - more frequent pulses for continuous flow
+            // Account for initial spring animation (~0.8s) + delay
+            const initialAnimationTime = 0.8 + (index * 0.1);
+            const pulseDelay = Math.max(0, averageDuration - initialAnimationTime);
+
+            return {
+              transition: {
+                duration: 0.3,
+                delay: pulseDelay,
+                repeat: Infinity,
+                repeatDelay: particleInterval - 0.3, // Pulse with each particle arrival
+                ease: "easeInOut",
+              },
+            };
+          };
+
+          const pulseProps = getPulseProps();
+
+          return (
+            <g key={sector.backendName || `sector-${index}`}>
+              {/* Connection highlight circle - consistent size */}
+              {isHovered && (
+                <motion.circle
+                  cx={pos.x}
+                  cy={pos.y}
+                  r="90"
+                  fill="none"
+                  stroke="hsl(var(--primary))"
+                  strokeWidth="1.5"
+                  strokeDasharray="4 8"
+                  opacity="0.25"
+                  initial={{ scale: 0.9, opacity: 0 }}
+                  animate={{ scale: 1.15, opacity: 0.3 }}
+                  transition={{ duration: 2, repeat: Infinity, ease: "easeInOut" }}
+                />
+              )}
+
+              {/* Sector node circle - consistent size */}
+              <motion.circle
+                cx={pos.x}
+                cy={pos.y}
+                r="32"
+                fill={`hsl(var(--sector-${sector.colorKey}))`}
+                fillOpacity="0.15"
+                stroke={`hsl(var(--sector-${sector.colorKey}))`}
+                strokeWidth={isHovered ? 3 : 2}
+                filter={isHovered ? "url(#glow)" : undefined}
+                initial={{ scale: 0 }}
+                animate={
+                  Object.keys(pulseProps).length > 0
+                    ? {
+                        scale: [1, 1.2, 1],
+                      }
+                    : { scale: 1 }
+                }
+                transition={
+                  Object.keys(pulseProps).length > 0
+                    ? {
+                        scale: {
+                          ...pulseProps.transition,
+                        },
+                        default: {
+                          type: "spring",
+                          stiffness: 200,
+                          damping: 15,
+                          delay: index * 0.1,
+                        },
+                      }
+                    : {
+                        type: "spring",
+                        stiffness: 200,
+                        damping: 15,
+                        delay: index * 0.1,
+                      }
+                }
+                onHoverStart={() => setHoveredSector(index)}
+                onHoverEnd={() => setHoveredSector(null)}
+                className="cursor-pointer"
+              />
+
+              {/* Sector icon circle background - consistent size */}
+              <motion.circle
+                cx={pos.x}
+                cy={pos.y}
+                r="22"
+                fill="hsl(var(--background))"
+                stroke={`hsl(var(--sector-${sector.colorKey}))`}
+                strokeWidth="2"
+                initial={{ scale: 0 }}
+                animate={
+                  Object.keys(pulseProps).length > 0
+                    ? {
+                        scale: [1, 1.2, 1],
+                      }
+                    : { scale: 1 }
+                }
+                transition={
+                  Object.keys(pulseProps).length > 0
+                    ? {
+                        scale: {
+                          ...pulseProps.transition,
+                        },
+                        default: {
+                          delay: index * 0.1 + 0.2,
+                        },
+                      }
+                    : { delay: index * 0.1 + 0.2 }
+                }
+              />
+
+
+              {/* Sector label */}
+              <motion.text
+                x={pos.x}
+                y={pos.y + 55}
+                textAnchor="middle"
+                fontSize="12"
+                fill="hsl(var(--foreground))"
+                fontWeight="600"
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                transition={{ delay: index * 0.1 + 0.3 }}
+              >
+                {t(`${sector.nameKey}.name`)}
+              </motion.text>
+
+              {/* Connection count badge - shows number of connections */}
+              {showStats && sectorConnections.length > 0 && (
+                <g>
+                  {/* Background circle - colored by sector */}
+                  <motion.circle
+                    cx={pos.x + 28}
+                    cy={pos.y - 28}
+                    r="14"
+                    fill={`hsl(var(--sector-${sector.colorKey}))`}
+                    stroke="hsl(var(--card))"
+                    strokeWidth="2"
+                    initial={{ scale: 0 }}
+                    animate={{ scale: 1 }}
+                    transition={{ delay: index * 0.1 + 0.4 }}
+                  />
+                  {/* Connection count text - use black for contrast on colored sector backgrounds */}
+                  <motion.text
+                    x={pos.x + 28}
+                    y={pos.y - 28}
+                    textAnchor="middle"
+                    dominantBaseline="central"
+                    fontSize="11"
+                    fontWeight="700"
+                    fill="black"
+                    initial={{ opacity: 0 }}
+                    animate={{ opacity: 1 }}
+                    transition={{ delay: index * 0.1 + 0.5 }}
+                  >
+                    {sectorConnections.length}
+                  </motion.text>
+                  <title>{sectorConnections.length} resource exchange connections</title>
+                </g>
+              )}
+            </g>
+          );
+        })}
+        {/* Sector icons using foreignObject - native SVG coordinate system */}
+        {dynamicSectors.map((sector, index) => {
+          const pos = sectorPositions[index];
+          if (!pos) return null;
+
+          const bounds = layoutCalculator.getForeignObjectBounds(pos.x, pos.y, 44);
+
+          return (
+            <foreignObject
+              key={`icon-${sector.backendName || index}`}
+              x={bounds.x}
+              y={bounds.y}
+              width={bounds.width}
+              height={bounds.height}
+              style={{ overflow: 'visible' }}
+            >
+              <motion.div
+                className="flex items-center justify-center w-full h-full rounded-full bg-background border-2 pointer-events-none"
+                style={{
+                  borderColor: `hsl(var(--sector-${sector.colorKey}))`,
+                }}
+                initial={{ scale: 0, opacity: 0 }}
+                animate={{ scale: 1, opacity: 1 }}
+                transition={{ delay: index * 0.1 + 0.2 }}
+              >
+                {React.cloneElement(sector.icon, {
+                  className: `w-5 h-5 text-sector-${sector.colorKey}`,
+                })}
+              </motion.div>
+            </foreignObject>
+          );
+        })}
+        {/* Resource type icons using foreignObject - native SVG coordinate system */}
+        {connections.map((conn, idx) => {
+          const fromPos = sectorPositions[conn.from];
+          const toPos = sectorPositions[conn.to];
+          if (!fromPos || !toPos) return null;
+
+          const sourceSector = dynamicSectors[conn.from];
+          if (!sourceSector) return null;
+
+          const isActive = activeConnections.has(`conn-${idx}`) || hoveredSector === null;
+          const resourceType = RESOURCE_TYPES.find(r => r.type === conn.resourceType);
+          if (!resourceType) return null;
+
+          const ResourceIcon = resourceType.icon;
+
+          // Check if this is a bidirectional exchange (both A→B and B→A exist)
+          const reverseConnection = connections.find(
+            c => c.from === conn.to && c.to === conn.from
+          );
+          const isBidirectional = !!reverseConnection;
+
+          // Calculate resource icon position using layout calculator
+          const resourceIconPos = layoutCalculator.calculateResourceIconPosition(
+            fromPos,
+            toPos,
+            isBidirectional,
+            conn.from,
+            conn.to,
+            showStats
+          );
+
+          const bounds = layoutCalculator.getForeignObjectBounds(resourceIconPos.x, resourceIconPos.y, 28);
+
+          return (
+            <foreignObject
+              key={`resource-icon-${idx}`}
+              x={bounds.x}
+              y={bounds.y}
+              width={bounds.width}
+              height={bounds.height}
+              style={{ overflow: 'visible' }}
+            >
+              <motion.div
+                className="flex items-center justify-center w-full h-full rounded-full bg-background border-2 pointer-events-none shadow-md"
+                style={{
+                  borderColor: `hsl(var(--sector-${sourceSector.colorKey}))`,
+                }}
+                initial={{ opacity: 0, scale: 0 }}
+                animate={{
+                  opacity: isActive ? 1 : 0,
+                  scale: isActive ? 1 : 0,
+                }}
+                transition={{ duration: 0.3 }}
+              >
+                <ResourceIcon className={`w-4 h-4 ${resourceType.color}`} />
+              </motion.div>
+            </foreignObject>
+          );
+        })}
+        </svg>
+      </div>
+
+      {/* Legend - moved below the animation */}
+      <div className="flex gap-4 items-center bg-background/80 backdrop-blur-sm px-4 py-2 rounded-full border shadow-lg">
+        <span className="text-xs text-muted-foreground font-medium">Resource Exchanges:</span>
+        {RESOURCE_TYPES.map((resource) => {
+          const Icon = resource.icon;
+          return (
+            <div key={resource.type} className="flex items-center gap-1.5">
+              <Icon className={`w-3 h-3 ${resource.color}`} />
+              <span className="text-xs text-muted-foreground capitalize">{resource.type}</span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+
+export default React.memo(ResourceExchangeVisualization);

bugulma/frontend/components/landing/SectorCard.tsx

@@ -0,0 +1,50 @@
+import React, { useCallback } from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { Sector } from '@/types.ts';
+import { Card } from '@/components/ui/Card.tsx';
+
+interface SectorCardProps {
+  sector: Sector;
+  onNavigateToMap: (sectorName: string) => void;
+}
+
+const SectorCard: React.FC<SectorCardProps> = ({ sector, onNavigateToMap }) => {
+  const { t } = useTranslation();
+
+  // Use backendName if available (for dynamic sectors), otherwise use the nameKey directly
+  const backendSectorKey = sector.backendName || sector.nameKey;
+
+  const handleClick = useCallback(() => {
+    onNavigateToMap(backendSectorKey);
+  }, [onNavigateToMap, backendSectorKey]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        onNavigateToMap(backendSectorKey);
+      }
+    },
+    [onNavigateToMap, backendSectorKey]
+  );
+
+  return (
+    <Card
+      as="button"
+      variant="interactive"
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      className="p-6 flex flex-col items-start text-left group"
+    >
+      <div
+        className={`h-12 w-12 rounded-lg flex items-center justify-center bg-sector-${sector.colorKey}/10 mb-4 group-hover:bg-sector-${sector.colorKey}/20 transition-colors duration-300`}
+      >
+        {React.cloneElement(sector.icon, { className: `h-7 w-7 text-sector-${sector.colorKey}` })}
+      </div>
+      <p className="font-semibold text-lg mb-1">{t(`${sector.nameKey}.name`)}</p>
+      <p className="text-sm text-muted-foreground">{t(`${sector.nameKey}.desc`)}</p>
+    </Card>
+  );
+};
+
+export default SectorCard;

bugulma/frontend/components/landing/Sectors.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { useDynamicSectors } from '@/hooks/useDynamicSectors.ts';
+import SectionHeader from '@/components/layout/SectionHeader.tsx';
+import { Container, Grid } from '@/components/ui/layout';
+import SectorCard from '@/components/landing/SectorCard.tsx';
+
+interface SectorsProps {
+  onNavigateToMap: (sector?: string) => void;
+}
+
+const Sectors = ({ onNavigateToMap }: SectorsProps) => {
+  const { t } = useTranslation();
+  const { sectors: dynamicSectors, isLoading, error } = useDynamicSectors(6);
+
+  return (
+    <section
+      className="bg-muted/50 min-h-screen flex items-center scroll-snap-align-start"
+      aria-labelledby="sectors-title"
+    >
+      <Container className="py-16 sm:py-24 w-full">
+        <SectionHeader
+          id="sectors-title"
+          title={t('sectors.title')}
+          subtitle={t('sectors.subtitle')}
+          className="mb-12 sm:mb-16"
+        />
+        <Grid cols={{ sm: 2, lg: 4 }} gap="lg">
+          {isLoading ? (
+            // Loading state - show skeleton placeholders
+            Array.from({ length: 6 }, (_, i) => (
+              <div key={i} className="animate-pulse">
+                <div className="bg-muted rounded-lg p-6 h-32"></div>
+              </div>
+            ))
+          ) : error ? (
+            // Error state - show error message
+            <div className="col-span-full text-center py-8">
+              <p className="text-muted-foreground">{t('common.error')}</p>
+            </div>
+          ) : dynamicSectors.length === 0 ? (
+            // Empty state - show loading until data arrives
+            <div className="col-span-full text-center py-8">
+              <p className="text-muted-foreground">Loading sectors...</p>
+            </div>
+          ) : (
+            // Success state - use dynamic sectors
+            dynamicSectors.map((sector) => (
+              <SectorCard key={sector.backendName} sector={sector} onNavigateToMap={onNavigateToMap} />
+            ))
+          )}
+        </Grid>
+      </Container>
+    </section>
+  );
+};
+
+export default React.memo(Sectors);

bugulma/frontend/components/landing/SymbiosisDemo.tsx

@@ -0,0 +1,175 @@
+import { AnimatePresence, motion } from 'framer-motion';
+import React, { useCallback, useMemo, useState } from 'react';
+import { symbiosisExamples } from '@/data/symbiosisExamples.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import SectionHeader from '@/components/layout/SectionHeader.tsx';
+import Button from '@/components/ui/Button.tsx';
+import { Container, Flex, Grid } from '@/components/ui/layout';
+import Select from '@/components/ui/Select.tsx';
+import DemoCard from '@/components/landing/DemoCard.tsx';
+
+interface SymbiosisDemoProps {
+  onNavigateToMap: (page: 'map') => void;
+}
+
+const SymbiosisDemo = ({ onNavigateToMap }: SymbiosisDemoProps) => {
+  const { t } = useTranslation();
+
+  // State now holds only the key of the selected offer.
+  const [selectedOfferKey, setSelectedOfferKey] = useState(symbiosisExamples[0].offer.key);
+
+  // Derive the selected offer object from the key using useMemo for performance.
+  const selectedOffer = useMemo(
+    () => symbiosisExamples.find((ex) => ex.offer.key === selectedOfferKey) || null,
+    [selectedOfferKey]
+  );
+
+  // Derive the available needs based on the selected offer.
+  const availableNeeds = useMemo(() => selectedOffer?.needs || [], [selectedOffer]);
+
+  // Initialize selected need key based on available needs
+  const initialSelectedNeedKey = availableNeeds[0]?.key || '';
+  const [selectedNeedKey, setSelectedNeedKey] = useState(initialSelectedNeedKey);
+
+  // Derive the selected need object from its key.
+  const selectedNeed = useMemo(
+    () => availableNeeds.find((n) => n.key === selectedNeedKey) || null,
+    [availableNeeds, selectedNeedKey]
+  );
+
+  // Event handlers now only update the keys.
+  const handleOfferChange = useCallback((e: React.ChangeEvent<HTMLSelectElement>) => {
+    setSelectedOfferKey(e.target.value);
+  }, []);
+
+  const handleNeedChange = useCallback((e: React.ChangeEvent<HTMLSelectElement>) => {
+    setSelectedNeedKey(e.target.value);
+  }, []);
+
+  const translatedSectors = useMemo(
+    () => ({
+      production: t('sectors.production'),
+      construction: t('sectors.construction'),
+      recreation: t('sectors.recreation'),
+      logistics: t('sectors.logistics'),
+    }),
+    [t]
+  );
+
+  return (
+    <section
+      className="bg-background min-h-screen flex items-center scroll-snap-align-start"
+      aria-labelledby="symbiosis-demo-title"
+    >
+      <Container className="py-16 sm:py-24 w-full">
+        <SectionHeader
+          id="symbiosis-demo-title"
+          title={t('symbiosisDemo.title')}
+          subtitle={t('symbiosisDemo.subtitle')}
+          className="mb-10 sm:mb-12"
+        />
+        <Grid cols={{ md: 2 }} gap="md" className="mb-12">
+          <div>
+            <label htmlFor="offer-select" className="block text-sm font-medium mb-1">
+              {t('symbiosisDemo.offerLabel')}
+            </label>
+            <Select id="offer-select" value={selectedOfferKey} onChange={handleOfferChange}>
+              {symbiosisExamples.map((ex) => (
+                <option key={ex.offer.key} value={ex.offer.key}>
+                  {t(ex.offer.nameKey)}
+                </option>
+              ))}
+            </Select>
+          </div>
+          <div>
+            <label htmlFor="need-select" className="block text-sm font-medium mb-1">
+              {t('symbiosisDemo.needLabel')}
+            </label>
+            <Select
+              id="need-select"
+              value={selectedNeedKey}
+              onChange={handleNeedChange}
+              disabled={!selectedOffer}
+            >
+              {availableNeeds.map((need) => (
+                <option key={need.key} value={need.key}>
+                  {t(need.nameKey)}
+                </option>
+              ))}
+            </Select>
+          </div>
+        </Grid>
+
+        <Flex
+          direction="col"
+          align="center"
+          justify="between"
+          gap="2xl"
+          className="relative mt-16 sm:flex-row sm:gap-0"
+        >
+          {selectedOffer && (
+            <DemoCard
+              icon={selectedOffer.offer.icon}
+              sector={translatedSectors[selectedOffer.offer.sector]}
+              item={t(selectedOffer.offer.nameKey)}
+              type="Offer"
+            />
+          )}
+
+          <div className="w-full sm:w-2/12 h-16 sm:h-auto flex items-center justify-center">
+            <svg className="w-full h-full" viewBox="0 0 100 100" preserveAspectRatio="none">
+              <motion.path
+                key={`${selectedOffer?.offer.key}-${selectedNeed?.key}`}
+                d="M 5 50 Q 50 20 95 50"
+                stroke="hsl(var(--primary))"
+                strokeWidth="2"
+                fill="none"
+                strokeDasharray="4 4"
+                initial={{ pathLength: 0, opacity: 0 }}
+                animate={{ pathLength: 1, opacity: 1 }}
+                transition={{ duration: 0.8, ease: 'easeInOut' }}
+              />
+            </svg>
+          </div>
+
+          {selectedNeed && (
+            <DemoCard
+              icon={selectedNeed.icon}
+              sector={translatedSectors[selectedNeed.sector]}
+              item={t(selectedNeed.nameKey)}
+              type="Need"
+            />
+          )}
+        </Flex>
+
+        <AnimatePresence mode="wait">
+          <motion.div
+            key={selectedNeed?.key}
+            initial={{ opacity: 0, y: 10 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -10 }}
+            transition={{ duration: 0.3 }}
+            className="mt-12 text-center max-w-2xl mx-auto p-4 bg-muted rounded-lg"
+            aria-live="polite"
+          >
+            <p className="text-lg text-foreground">
+              {selectedNeed ? t(selectedNeed.descriptionKey) : ' '}
+            </p>
+          </motion.div>
+        </AnimatePresence>
+
+        <div className="text-center mt-16">
+          <Button
+            size="lg"
+            onClick={() => onNavigateToMap('map')}
+            className="shadow-lg shadow-primary/20 hover:shadow-xl hover:shadow-primary/30"
+          >
+            {t('symbiosisDemo.ctaButton')}
+          </Button>
+        </div>
+      </Container>
+    </section>
+  );
+};
+
+export default React.memo(SymbiosisDemo);

bugulma/frontend/components/layout/AnimatedSection.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+import { motion } from 'framer-motion';
+import { useAnimatedSection } from '@/hooks/useAnimatedSection';
+
+interface AnimatedSectionProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+const AnimatedSection: React.FC<AnimatedSectionProps> = ({ children, className }) => {
+  const { ref, isInView } = useAnimatedSection();
+
+  return (
+    <motion.div
+      ref={ref}
+      initial={{ opacity: 0, y: 50 }}
+      animate={isInView ? { opacity: 1, y: 0 } : {}}
+      transition={{ duration: 0.6, ease: 'easeOut' }}
+      className={`relative ${className || ''}`}
+      style={{ position: 'relative' }}
+    >
+      {children}
+    </motion.div>
+  );
+};
+
+export default AnimatedSection;

bugulma/frontend/components/layout/BrandIdentity.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import BrandLogo from '@/components/layout/BrandLogo.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+
+interface BrandIdentityProps {
+  showPulse?: boolean;
+  onClick?: () => void;
+  className?: string;
+}
+
+const BrandIdentity = ({ showPulse, onClick, className }: BrandIdentityProps) => {
+  const { t } = useTranslation();
+  return (
+    <div
+      onClick={onClick}
+      className={`flex items-center gap-2 ${onClick ? 'cursor-pointer' : ''} ${className}`}
+    >
+      <BrandLogo showPulse={showPulse} />
+      <div className="hidden sm:block leading-tight">
+        <p className="text-xs uppercase tracking-wide text-muted-foreground">
+          {t('topBar.subTitle')}
+        </p>
+        <p className="font-serif text-xl font-semibold text-foreground">{t('topBar.title')}</p>
+      </div>
+    </div>
+  );
+};
+
+export default BrandIdentity;

bugulma/frontend/components/layout/BrandLogo.tsx

@@ -0,0 +1,28 @@
+import Logo from '@/components/ui/Logo';
+
+interface BrandLogoProps {
+  showPulse?: boolean;
+  className?: string;
+  size?: number;
+}
+
+const BrandLogo = ({ showPulse = false, className = '', size }: BrandLogoProps) => {
+  // Extract size from className if provided (e.g., h-20 w-20 = 80px)
+  const sizeMatch = className.match(/h-(\d+)|w-(\d+)/);
+  const extractedSize = sizeMatch ? parseInt(sizeMatch[1] || sizeMatch[2]) * 4 : undefined;
+  const logoSize = size || extractedSize || 40;
+
+  return (
+    <div
+      className={`relative rounded-lg flex items-center justify-center shadow-sm ${className}`}
+      style={size ? { width: `${size}px`, height: `${size}px` } : undefined}
+    >
+      <Logo size={logoSize} className="h-full w-full" />
+      {showPulse && (
+        <span className="absolute -top-1 -right-1 h-2.5 w-2.5 rounded-full bg-success ring-2 ring-background animate-pulse" />
+      )}
+    </div>
+  );
+};
+
+export default BrandLogo;

bugulma/frontend/components/layout/Footer.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import BrandLogo from '@/components/layout/BrandLogo.tsx';
+
+interface FooterProps {
+  onNavigate: (page: 'about' | 'contact' | 'privacy') => void;
+}
+
+const Footer = ({ onNavigate }: FooterProps) => {
+  const { t } = useTranslation();
+  return (
+    <footer className="bg-muted/50 border-t">
+      <div className="mx-auto max-w-6xl px-4 py-8">
+        <div className="flex flex-col md:flex-row justify-between items-center gap-6">
+          <div className="flex items-center gap-2">
+            <BrandLogo />
+            <div className="leading-tight">
+              <p className="font-serif text-lg font-semibold text-foreground">
+                {t('topBar.title')}
+              </p>
+              <p className="text-sm text-muted-foreground">
+                {t('footer.copyright', { year: new Date().getFullYear() })}
+              </p>
+            </div>
+          </div>
+          <nav
+            className="flex flex-wrap gap-x-6 gap-y-2 justify-center"
+            aria-label="Footer navigation"
+          >
+            <button
+              onClick={() => onNavigate('about')}
+              className="text-sm text-muted-foreground hover:text-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 rounded px-2 py-1"
+              aria-label={`Navigate to ${t('footer.links.about')}`}
+            >
+              {t('footer.links.about')}
+            </button>
+            <button
+              onClick={() => onNavigate('contact')}
+              className="text-sm text-muted-foreground hover:text-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 rounded px-2 py-1"
+              aria-label={`Navigate to ${t('footer.links.contact')}`}
+            >
+              {t('footer.links.contact')}
+            </button>
+            <button
+              onClick={() => onNavigate('privacy')}
+              className="text-sm text-muted-foreground hover:text-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 rounded px-2 py-1"
+              aria-label={`Navigate to ${t('footer.links.privacy')}`}
+            >
+              {t('footer.links.privacy')}
+            </button>
+          </nav>
+        </div>
+      </div>
+    </footer>
+  );
+};
+
+export default React.memo(Footer);

bugulma/frontend/components/layout/Header.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+
+interface HeaderSectionProps {
+  children: React.ReactNode;
+  className?: string;
+  align?: 'left' | 'center' | 'right';
+}
+
+export const HeaderSection: React.FC<HeaderSectionProps> = ({
+  children,
+  className = '',
+  align = 'left'
+}) => {
+  const alignClasses = {
+    left: 'justify-start',
+    center: 'justify-center',
+    right: 'justify-end'
+  };
+
+  return (
+    <div className={`flex items-center gap-2 ${alignClasses[align]} ${className}`}>
+      {children}
+    </div>
+  );
+};
+
+interface HeaderLayoutProps {
+  children: React.ReactNode;
+  className?: string;
+  variant?: 'default' | 'map' | 'transparent';
+}
+
+export const HeaderLayout: React.FC<HeaderLayoutProps> = ({
+  children,
+  className = '',
+  variant = 'default'
+}) => {
+  const variantClasses = {
+    default: 'border-b bg-background/70 backdrop-blur shrink-0 z-20',
+    map: 'border-b bg-background/70 backdrop-blur shrink-0 z-20',
+    transparent: 'shrink-0 z-20'
+  };
+
+  return (
+    <header className={`${variantClasses[variant]} ${className}`}>
+      <div className="mx-auto max-w-full flex items-center justify-between flex-wrap px-4 py-3 gap-3">
+        {children}
+      </div>
+    </header>
+  );
+};
+
+export default HeaderLayout;

bugulma/frontend/components/layout/HeaderActions.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useAuth } from '@/contexts/AuthContext';
+import { useTranslation } from '@/hooks/useI18n';
+import { LogIn } from 'lucide-react';
+import Button from '@/components/ui/Button';
+import LanguageSwitcher from '@/components/ui/LanguageSwitcher';
+import ThemeToggle from '@/components/ui/ThemeToggle';
+
+interface HeaderActionsProps {
+  showThemeToggle?: boolean;
+  showLanguageSwitcher?: boolean;
+  showAuthButton?: boolean;
+  className?: string;
+}
+
+export const HeaderActions: React.FC<HeaderActionsProps> = ({
+  showThemeToggle = true,
+  showLanguageSwitcher = true,
+  showAuthButton = true,
+  className = ''
+}) => {
+  const { t } = useTranslation();
+  const { isAuthenticated, user } = useAuth();
+  const navigate = useNavigate();
+
+  const handleAuthClick = () => {
+    if (!isAuthenticated) {
+      navigate('/login');
+    } else if (user?.role === 'admin') {
+      navigate('/admin');
+    } else {
+      navigate('/dashboard');
+    }
+  };
+
+  return (
+    <div className={`flex items-center gap-2 ${className}`}>
+      {showThemeToggle && <ThemeToggle />}
+      {showLanguageSwitcher && <LanguageSwitcher />}
+      {showAuthButton && (
+        <Button
+          onClick={handleAuthClick}
+          variant="primary-ghost"
+          aria-label={t('topBar.loginButton')}
+        >
+          <LogIn className="h-4 sm:mr-2 text-current w-4" />
+          <span className="hidden sm:inline">
+            {isAuthenticated
+              ? user?.role === 'admin'
+                ? t('topBar.adminButton')
+                : t('topBar.dashboardButton')
+              : t('topBar.loginButton')}
+          </span>
+        </Button>
+      )}
+    </div>
+  );
+};
+
+export default HeaderActions;

bugulma/frontend/components/layout/MainLayout.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import TopBar from '@/components/layout/TopBar.tsx';
+import Footer from '@/components/layout/Footer.tsx';
+
+interface MainLayoutProps {
+  children?: React.ReactNode;
+  onNavigate: (page: 'about' | 'contact' | 'privacy') => void;
+  className?: string;
+}
+
+export const MainLayout = ({ children, onNavigate, className = '' }: MainLayoutProps) => (
+  <div className="flex flex-col min-h-screen" style={{ position: 'relative' }}>
+    <TopBar />
+    <main className={`flex-1 ${className}`} style={{ position: 'relative' }}>{children}</main>
+    <Footer onNavigate={onNavigate} />
+  </div>
+);

bugulma/frontend/components/layout/PageHeader.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { ArrowLeft } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+
+interface PageHeaderProps {
+  title: string;
+  subtitle?: string;
+  onBack?: () => void;
+  children?: React.ReactNode;
+}
+
+const PageHeader = ({ title, subtitle, onBack, children }: PageHeaderProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <header className="mb-8">
+      {onBack && (
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="mb-4 -ml-4 text-muted-foreground hover:text-foreground"
+        >
+          <ArrowLeft className="h-4 mr-2 text-current w-4" />
+          {t('organizationPage.navigateBack')}
+        </Button>
+      )}
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="font-serif text-2xl sm:text-3xl font-bold tracking-tight text-foreground">
+            {title}
+          </h1>
+          {subtitle && (
+            <p className="mt-1 text-base sm:text-lg text-muted-foreground">{subtitle}</p>
+          )}
+        </div>
+        {children && <div className="flex items-center space-x-2">{children}</div>}
+      </div>
+    </header>
+  );
+};
+
+export default PageHeader;

bugulma/frontend/components/layout/SectionHeader.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+interface SectionHeaderProps {
+  id?: string;
+  title: string;
+  subtitle?: string;
+  className?: string;
+}
+
+const SectionHeader = ({ id, title, subtitle, className = '' }: SectionHeaderProps) => (
+  <div className={`text-center ${className}`}>
+    <h2
+      id={id}
+      className="font-serif text-3xl md:text-4xl font-semibold tracking-tight text-foreground mb-4"
+    >
+      {title}
+    </h2>
+    {subtitle && (
+      <p className="text-base md:text-lg text-muted-foreground max-w-3xl mx-auto">{subtitle}</p>
+    )}
+  </div>
+);
+
+export default React.memo(SectionHeader);

bugulma/frontend/components/layout/StaticPageLayout.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import Button from '@/components/ui/Button.tsx';
+import { ArrowLeft } from 'lucide-react';
+
+interface StaticPageLayoutProps {
+  onNavigateBack: () => void;
+  title: string;
+  children?: React.ReactNode;
+}
+
+const StaticPageLayout = ({ onNavigateBack, title, children }: StaticPageLayoutProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className="mx-auto max-w-4xl px-4 py-16 sm:py-24">
+      <Button
+        variant="ghost"
+        onClick={onNavigateBack}
+        className="mb-8 -ml-4 text-base text-muted-foreground hover:text-foreground"
+      >
+        <ArrowLeft className="h-4 mr-2 text-current w-4" />
+        {t('organizationPage.navigateBack')}
+      </Button>
+      <div className="prose max-w-none">
+        <h1>{title}</h1>
+        {children}
+      </div>
+    </div>
+  );
+};
+
+export default StaticPageLayout;

bugulma/frontend/components/layout/StaticPageScaffold.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { useNavigation } from '@/hooks/useNavigation.tsx';
+import { MainLayout } from '@/components/layout/MainLayout.tsx';
+import StaticPageLayout from '@/components/layout/StaticPageLayout.tsx';
+
+interface StaticPageScaffoldProps {
+  title: string;
+  children: React.ReactNode;
+  mainLayoutClassName?: string;
+}
+
+const StaticPageScaffold = ({
+  title,
+  children,
+  mainLayoutClassName = 'bg-muted/30',
+}: StaticPageScaffoldProps) => {
+  const { handleBackNavigation, handleFooterNavigate } = useNavigation();
+
+  return (
+    <MainLayout onNavigate={handleFooterNavigate} className={mainLayoutClassName}>
+      <StaticPageLayout onNavigateBack={handleBackNavigation} title={title}>
+        {children}
+      </StaticPageLayout>
+    </MainLayout>
+  );
+};
+
+export default StaticPageScaffold;

bugulma/frontend/components/layout/TopBar.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { useScrollListener } from '@/hooks/useScrollListener.ts';
+import { HeaderLayout, HeaderSection } from '@/components/layout/Header.tsx';
+import HeaderActions from '@/components/layout/HeaderActions.tsx';
+import SearchBar from '@/components/ui/SearchBar.tsx';
+import BrandIdentity from '@/components/layout/BrandIdentity.tsx';
+
+interface TopBarProps {
+  showSearch?: boolean;
+  searchTerm?: string;
+  onSearchChange?: (term: string) => void;
+  onSearchSubmit?: () => void;
+}
+
+const TopBar = ({
+  showSearch = false,
+  searchTerm = '',
+  onSearchChange,
+  onSearchSubmit,
+}: TopBarProps) => {
+  const isScrolled = useScrollListener(10);
+
+  return (
+    <HeaderLayout
+      variant="transparent"
+      className={`sticky top-0 z-30 transition-all duration-300 ${isScrolled ? 'bg-background/80 backdrop-blur-lg shadow-sm border-b border-border/50' : 'bg-transparent'}`}
+    >
+      <HeaderSection>
+        <BrandIdentity showPulse />
+      </HeaderSection>
+
+      {showSearch && (
+        <HeaderSection align="center" className="order-3 md:order-2">
+          <SearchBar
+            value={searchTerm}
+            onChange={onSearchChange || (() => {})}
+            onSubmit={onSearchSubmit}
+            navigateOnEnter={!onSearchSubmit}
+            containerClassName="w-full md:w-auto md:flex-1 max-w-md"
+          />
+        </HeaderSection>
+      )}
+
+      <HeaderSection align="right" className={`gap-3 ${showSearch ? 'order-2 md:order-3' : ''}`}>
+        <HeaderActions />
+      </HeaderSection>
+    </HeaderLayout>
+  );
+};
+
+export default React.memo(TopBar);

bugulma/frontend/components/map/HistoricalContextAI.tsx

@@ -0,0 +1,46 @@
+import React, { useCallback } from 'react';
+import { HistoricalLandmark } from '@/types.ts';
+import Button from '@/components/ui/Button.tsx';
+import Spinner from '@/components/ui/Spinner.tsx';
+import ErrorMessage from '@/components/ui/ErrorMessage.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { useGenerateHistoricalContext } from '@/hooks/useGemini.ts';
+
+interface HistoricalContextAIProps {
+  landmark: HistoricalLandmark;
+}
+
+const HistoricalContextAI = ({ landmark }: HistoricalContextAIProps) => {
+  const { t } = useTranslation();
+  const { data, error, isPending, refetch } = useGenerateHistoricalContext(landmark, t);
+
+  const handleGenerate = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  return (
+    <div>
+      {!data && (
+        <div className="text-center">
+          <p className="mb-2 text-sm text-muted-foreground">{t('historicalContext.prompt')}</p>
+          <Button onClick={handleGenerate} disabled={isPending} size="sm">
+            {isPending ? <Spinner className="h-4 w-4" /> : t('historicalContext.generateButton')}
+          </Button>
+        </div>
+      )}
+
+      {error && <ErrorMessage message={error.message} />}
+
+      {data && (
+        <div>
+          <h4 className="mb-2 text-base font-semibold">{t('historicalContext.title')}</h4>
+          <blockquote className="border-l-4 border-primary pl-4 italic text-muted-foreground">
+            {data}
+          </blockquote>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default React.memo(HistoricalContextAI);

bugulma/frontend/components/map/HistoricalMarkers.tsx

@@ -0,0 +1,93 @@
+import { LatLngTuple } from 'leaflet';
+import React, { useCallback } from 'react';
+import { Marker, Popup } from 'react-leaflet';
+import { useMapActions } from '@/contexts/MapContexts.tsx';
+import { HistoricalLandmark } from '@/types.ts';
+import { getCachedHistoricalIcon } from '@/utils/map/iconCache.ts';
+
+interface HistoricalMarkersProps {
+  landmarks: HistoricalLandmark[];
+  selectedLandmark: HistoricalLandmark | null;
+  hoveredLandmarkId: string | null;
+}
+
+/**
+ * Individual historical marker component memoized to prevent unnecessary re-renders
+ */
+const HistoricalMarker = React.memo<{
+  landmark: HistoricalLandmark;
+  isSelected: boolean;
+  isHovered: boolean;
+  onSelect: (landmark: HistoricalLandmark) => void;
+  onHover: (landmarkId: string | null) => void;
+}>(({ landmark, isSelected, isHovered, onSelect, onHover }) => {
+  const position: LatLngTuple = [landmark.location.lat, landmark.location.lng];
+  const icon = getCachedHistoricalIcon(landmark.id, landmark, isSelected, isHovered);
+
+  const handleClick = useCallback(() => {
+    onSelect(landmark);
+  }, [landmark, onSelect]);
+
+  const handleMouseOver = useCallback(() => {
+    onHover(landmark.id);
+  }, [landmark.id, onHover]);
+
+  const handleMouseOut = useCallback(() => {
+    onHover(null);
+  }, [onHover]);
+
+  if (!landmark.location) return null;
+
+  return (
+    <Marker
+      position={position}
+      icon={icon}
+      eventHandlers={{
+        click: handleClick,
+        mouseover: handleMouseOver,
+        mouseout: handleMouseOut,
+      }}
+    >
+      <Popup>
+        <div>
+          <h3 className="text-base font-semibold">{landmark.name}</h3>
+          <p className="text-sm text-muted-foreground">{landmark.period}</p>
+        </div>
+      </Popup>
+    </Marker>
+  );
+});
+
+HistoricalMarker.displayName = 'HistoricalMarker';
+
+const HistoricalMarkers: React.FC<HistoricalMarkersProps> = ({
+  landmarks,
+  selectedLandmark,
+  hoveredLandmarkId,
+}) => {
+  const { handleSelectLandmark, setHoveredLandmarkId } = useMapActions();
+
+  return (
+    <>
+      {landmarks.map((landmark) => {
+        if (!landmark.location) return null;
+
+        const isSelected = selectedLandmark?.id === landmark.id;
+        const isHovered = hoveredLandmarkId === landmark.id;
+
+        return (
+          <HistoricalMarker
+            key={landmark.id}
+            landmark={landmark}
+            isSelected={isSelected}
+            isHovered={isHovered}
+            onSelect={handleSelectLandmark}
+            onHover={setHoveredLandmarkId}
+          />
+        );
+      })}
+    </>
+  );
+};
+
+export default React.memo(HistoricalMarkers);

bugulma/frontend/components/map/HistoricalSidebarPreview.tsx

@@ -0,0 +1,116 @@
+import React, { useMemo } from 'react';
+import { useMapActions, useMapInteraction } from '@/contexts/MapContexts.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { useOrganizations } from '@/hooks/useOrganizations.ts';
+import { ExternalLink } from 'lucide-react';
+import { Building2 } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+import Separator from '@/components/ui/Separator.tsx';
+import HistoricalContextAI from '@/components/map/HistoricalContextAI.tsx';
+
+const InfoLine = ({ label, value }: { label: string; value?: string | React.ReactNode }) => {
+  if (!value) return null;
+  return (
+    <>
+      <dt className="text-xs text-muted-foreground">{label}</dt>
+      <dd className="text-sm font-medium mb-3">{value}</dd>
+    </>
+  );
+};
+
+const HistoricalSidebarPreview = () => {
+  const { organizations } = useOrganizations();
+  const { t } = useTranslation();
+  const { selectedLandmark: landmark } = useMapInteraction();
+  const { handleViewOrganization: onViewOrganization } = useMapActions();
+
+  const relatedOrg = useMemo(() => {
+    if (!landmark?.relatedOrgId) return null;
+    return organizations.find((org) => org.ID === landmark.relatedOrgId) || null;
+  }, [landmark, organizations]);
+
+  if (!landmark) return null;
+
+  return (
+    <div className="p-4 space-y-4">
+      {landmark.imageUrl ? (
+        <div className="w-full h-40 rounded-lg overflow-hidden bg-muted">
+          <img
+            src={landmark.imageUrl}
+            alt={landmark.name}
+            className="w-full h-full object-cover"
+            loading="lazy"
+            decoding="async"
+            onError={(e) => {
+              (e.target as HTMLImageElement).style.display = 'none';
+            }}
+          />
+        </div>
+      ) : (
+        <div className="w-full h-40 rounded-lg bg-muted flex items-center justify-center">
+          <Building2 className="h-16 h-4 text-current text-muted-foreground w-16 w-4" />
+        </div>
+      )}
+
+      <div>
+        <p className="text-sm text-primary">{landmark.period}</p>
+        <h3 className="text-lg font-semibold">{landmark.name}</h3>
+      </div>
+
+      <Separator />
+
+      <HistoricalContextAI landmark={landmark} />
+
+      <Separator />
+
+      <div>
+        <h4 className="text-base font-semibold mb-3">Местоположение и статус</h4>
+        <dl>
+          <InfoLine label="Адрес" value={landmark.address} />
+          <InfoLine label="Текущий статус" value={landmark.currentStatus} />
+          {relatedOrg && (
+            <>
+              <dt className="text-xs text-muted-foreground">Связанная организация</dt>
+              <dd className="text-sm font-medium">
+                {relatedOrg.Name}
+                <Button
+                  size="sm"
+                  className="w-full mt-2"
+                  onClick={() => onViewOrganization(relatedOrg)}
+                >
+                  <ExternalLink className="h-4 mr-2 text-current text-primary-foreground w-4" />
+                  {t('mapSidebar.details.viewOrganization')}
+                </Button>
+              </dd>
+            </>
+          )}
+        </dl>
+      </div>
+
+      <Separator />
+
+      <div>
+        <h4 className="text-base font-semibold mb-3">Исторический контекст</h4>
+        <dl>
+          <InfoLine label="Основатель/Владелец" value={landmark.builder} />
+          <InfoLine label="Архитектор" value={landmark.architect} />
+          <InfoLine label="Изначальное назначение" value={landmark.originalPurpose} />
+          {landmark.historicalNotes && landmark.historicalNotes.length > 0 && (
+            <InfoLine
+              label="Историческая справка"
+              value={
+                <ul className="space-y-1 list-disc list-inside">
+                  {landmark.historicalNotes.map((note, i) => (
+                    <li key={i}>{note}</li>
+                  ))}
+                </ul>
+              }
+            />
+          )}
+        </dl>
+      </div>
+    </div>
+  );
+};
+
+export default HistoricalSidebarPreview;

bugulma/frontend/components/map/LeafletMap.tsx

@@ -0,0 +1,282 @@
+import L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+import { useCallback, useEffect, useRef } from 'react';
+import { GeoJSON, MapContainer, TileLayer, useMap, useMapEvents } from 'react-leaflet';
+import MarkerClusterGroup from 'react-leaflet-markercluster';
+import 'react-leaflet-markercluster/styles';
+import { useMapFilter, useMapInteraction, useMapUI, useMapViewport } from '@/contexts/MapContexts.tsx';
+import bugulmaGeo from '@/data/bugulmaGeometry.json';
+import { useMapData } from '@/hooks/map/useMapData.ts';
+import HistoricalMarkers from '@/components/map/HistoricalMarkers.tsx';
+import MapControls from '@/components/map/MapControls.tsx';
+import OrganizationCenterHandler from '@/components/map/OrganizationCenterHandler.tsx';
+import OrganizationMarkers from '@/components/map/OrganizationMarkers.tsx';
+import SymbiosisLines from '@/components/map/SymbiosisLines.tsx';
+
+// Fix for default marker icon issue in Leaflet with webpack/vite
+delete (L.Icon.Default.prototype as unknown as { _getIconUrl?: unknown })._getIconUrl;
+L.Icon.Default.mergeOptions({
+  iconRetinaUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-icon-2x.png',
+  iconUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-icon.png',
+  shadowUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-shadow.png',
+});
+
+/**
+ * Component to handle map resize when sidebar opens/closes
+ * Leaflet needs to recalculate its size when container dimensions change
+ */
+const MapResizeHandler = () => {
+  const map = useMap();
+  const { isSidebarOpen } = useMapUI();
+  const resizeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    // Clear any pending resize
+    if (resizeTimeoutRef.current) {
+      clearTimeout(resizeTimeoutRef.current);
+    }
+
+    // Delay resize to allow CSS transition to complete
+    resizeTimeoutRef.current = setTimeout(() => {
+      map.invalidateSize();
+    }, 350); // Slightly longer than CSS transition (300ms)
+
+    return () => {
+      if (resizeTimeoutRef.current) {
+        clearTimeout(resizeTimeoutRef.current);
+      }
+    };
+  }, [map, isSidebarOpen]);
+
+  return null;
+};
+
+/**
+ * Component to sync Leaflet map view with context state
+ * Optimized to prevent infinite loops and unnecessary updates
+ */
+const MapSync = () => {
+  const { mapCenter, zoom, setZoom, setMapCenter } = useMapViewport();
+  const map = useMap();
+  const isUpdatingRef = useRef(false);
+  const lastUpdateRef = useRef<{ center: [number, number]; zoom: number } | null>(null);
+
+  // Sync context state to map (only when explicitly changed, not from map events)
+  useEffect(() => {
+    // Prevent updates during user interaction
+    if (isUpdatingRef.current) return;
+
+    const currentCenter = map.getCenter();
+    const centerDiff =
+      Math.abs(currentCenter.lat - mapCenter[0]) + Math.abs(currentCenter.lng - mapCenter[1]);
+    const zoomDiff = Math.abs(map.getZoom() - zoom);
+
+    // Only update if difference is significant (prevents micro-updates)
+    const shouldUpdate = zoomDiff > 0.1 || centerDiff > 0.0001 || !lastUpdateRef.current;
+
+    if (shouldUpdate) {
+      // Check if this update would cause a loop
+      const lastUpdate = lastUpdateRef.current;
+      if (
+        lastUpdate &&
+        lastUpdate.center[0] === mapCenter[0] &&
+        lastUpdate.center[1] === mapCenter[1] &&
+        lastUpdate.zoom === zoom
+      ) {
+        return;
+      }
+
+      isUpdatingRef.current = true;
+      map.setView(mapCenter, zoom, { animate: true });
+      lastUpdateRef.current = { center: mapCenter, zoom };
+
+      // Reset flag after animation completes
+      const timeoutId = setTimeout(() => {
+        isUpdatingRef.current = false;
+      }, 300);
+
+      return () => {
+        clearTimeout(timeoutId);
+      };
+    }
+  }, [map, mapCenter, zoom]);
+
+  // Sync map events to context (throttled to avoid excessive updates)
+  useMapEvents({
+    moveend: () => {
+      if (isUpdatingRef.current) return;
+      const center = map.getCenter();
+      const newCenter: [number, number] = [center.lat, center.lng];
+
+      // Only update if center actually changed
+      if (
+        !lastUpdateRef.current ||
+        Math.abs(lastUpdateRef.current.center[0] - newCenter[0]) > 0.0001 ||
+        Math.abs(lastUpdateRef.current.center[1] - newCenter[1]) > 0.0001
+      ) {
+        setMapCenter(newCenter);
+      }
+    },
+    zoomend: () => {
+      if (isUpdatingRef.current) return;
+      const newZoom = map.getZoom();
+
+      // Only update if zoom actually changed
+      if (!lastUpdateRef.current || Math.abs(lastUpdateRef.current.zoom - newZoom) > 0.1) {
+        setZoom(newZoom);
+      }
+    },
+  });
+
+  return null;
+};
+
+/**
+ * LeafletMap Component
+ *
+ * Renders an interactive map of Bugulma using Leaflet.
+ * Features:
+ * - Real city geometry from OSM Relation 9684457
+ * - Organization and historical landmark markers with clustering
+ * - AI-powered symbiosis connection visualization
+ * - Zoom and pan controls
+ */
+const LeafletMap = () => {
+  const { mapCenter, zoom } = useMapViewport();
+  const { selectedOrg, hoveredOrgId, selectedLandmark, hoveredLandmarkId, symbiosisResult } =
+    useMapInteraction();
+  const { historicalLandmarks } = useMapData();
+  const { filteredAndSortedOrgs } = useMapFilter();
+  const { mapViewMode } = useMapUI();
+
+  // GeoJSON style function - show only edges, no fill to avoid darkening the area
+  const geoJsonStyle = {
+    fillColor: 'transparent',
+    fillOpacity: 0,
+    color: 'hsl(var(--border))',
+    weight: 1.5,
+    opacity: 0.8,
+  };
+
+  // Optimize map container with performance settings
+  const whenCreated = useCallback((mapInstance: L.Map) => {
+    // Enable preferCanvas for better performance with many markers
+    mapInstance.options.preferCanvas = true;
+    // Optimize rendering
+    mapInstance.options.fadeAnimation = true;
+    mapInstance.options.zoomAnimation = true;
+    mapInstance.options.zoomAnimationThreshold = 4;
+
+    // Remove Leaflet attribution control (removes flag and "Leaflet" branding)
+    mapInstance.attributionControl.remove();
+  }, []);
+
+  return (
+    <MapContainer
+      center={mapCenter}
+      zoom={zoom}
+      minZoom={10}
+      maxZoom={18}
+      zoomControl={true}
+      scrollWheelZoom={true}
+      attributionControl={false}
+      className="bg-background h-full w-full"
+      preferCanvas={true}
+      fadeAnimation={true}
+      zoomAnimation={true}
+      zoomAnimationThreshold={4}
+      whenCreated={whenCreated}
+    >
+      <MapSync />
+      <MapResizeHandler />
+      <OrganizationCenterHandler />
+
+      {/* Map tile layer */}
+      <TileLayer
+        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
+        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+      />
+
+      {/* City boundary GeoJSON */}
+      {bugulmaGeo && (
+        <GeoJSON
+          data={bugulmaGeo as Parameters<typeof GeoJSON>[0]['data']}
+          style={geoJsonStyle}
+          onEachFeature={(feature, layer) => {
+            // Optional: Add feature interaction handlers here if needed
+            layer.on({
+              mouseover: () => {
+                layer.setStyle({ weight: 2, opacity: 1 });
+              },
+              mouseout: () => {
+                layer.setStyle({ weight: 1.5, opacity: 0.8 });
+              },
+            });
+          }}
+        />
+      )}
+
+      {/* Symbiosis connection lines */}
+      {mapViewMode === 'organizations' && symbiosisResult && selectedOrg && (
+        <SymbiosisLines
+          matches={symbiosisResult}
+          hoveredOrgId={hoveredOrgId}
+          selectedOrg={selectedOrg}
+        />
+      )}
+
+      {/* Organization markers with clustering */}
+      {mapViewMode === 'organizations' && (
+        <MarkerClusterGroup
+          chunkedLoading={true}
+          chunkDelay={50}
+          chunkInterval={100}
+          maxClusterRadius={80}
+          spiderfyOnMaxZoom={true}
+          showCoverageOnHover={false}
+          zoomToBoundsOnClick={true}
+          disableClusteringAtZoom={15}
+          removeOutsideVisibleBounds={false}
+          animate={true}
+          animateAddingMarkers={true}
+          spiderfyDistanceMultiplier={2}
+          spiderLegPolylineOptions={{
+            weight: 1.5,
+            color: 'hsl(var(--muted-foreground))',
+            opacity: 0.5,
+          }}
+          iconCreateFunction={(cluster) => {
+            const count = cluster.getChildCount();
+            const size = count < 10 ? 'small' : count < 100 ? 'medium' : 'large';
+            const className = `marker-cluster marker-cluster-${size}`;
+            return L.divIcon({
+              html: `<div><span>${count}</span></div>`,
+              className,
+              iconSize: L.point(40, 40),
+            });
+          }}
+        >
+          <OrganizationMarkers
+            organizations={filteredAndSortedOrgs}
+            selectedOrg={selectedOrg}
+            hoveredOrgId={hoveredOrgId}
+          />
+        </MarkerClusterGroup>
+      )}
+
+      {/* Historical landmark markers */}
+      {mapViewMode === 'historical' && (
+        <HistoricalMarkers
+          landmarks={historicalLandmarks}
+          selectedLandmark={selectedLandmark}
+          hoveredLandmarkId={hoveredLandmarkId}
+        />
+      )}
+
+      {/* Map controls */}
+      <MapControls />
+    </MapContainer>
+  );
+};
+
+export default LeafletMap;

bugulma/frontend/components/map/MapBoundsTracker.tsx

@@ -0,0 +1,119 @@
+import { LatLngBounds } from 'leaflet';
+import { useCallback, useEffect, useRef } from 'react';
+import { useMap, useMapEvents } from 'react-leaflet';
+import { useMapActions } from '@/contexts/MapContexts.tsx';
+
+/**
+ * Component to track map bounds and update context
+ * This enables viewport-based lazy loading of organizations
+ * Optimized with better debouncing and bounds comparison
+ */
+const MapBoundsTracker = () => {
+  const { setMapBounds } = useMapActions();
+  const boundsRef = useRef<LatLngBounds | null>(null);
+  const updateTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const isUpdatingRef = useRef(false);
+
+  /**
+   * Check if bounds have changed significantly
+   * Uses a more efficient comparison that considers both area and position
+   */
+  const hasBoundsChanged = useCallback(
+    (newBounds: LatLngBounds, oldBounds: LatLngBounds | null): boolean => {
+      if (!oldBounds) return true;
+
+      // Compare center position
+      const newCenter = newBounds.getCenter();
+      const oldCenter = oldBounds.getCenter();
+      const centerDiff =
+        Math.abs(newCenter.lat - oldCenter.lat) + Math.abs(newCenter.lng - oldCenter.lng);
+
+      // Compare bounds size (north-south and east-west spans)
+      const newSize = {
+        lat: newBounds.getNorth() - newBounds.getSouth(),
+        lng: newBounds.getEast() - newBounds.getWest(),
+      };
+      const oldSize = {
+        lat: oldBounds.getNorth() - oldBounds.getSouth(),
+        lng: oldBounds.getEast() - oldBounds.getWest(),
+      };
+      const sizeDiff = Math.abs(newSize.lat - oldSize.lat) + Math.abs(newSize.lng - oldSize.lng);
+
+      // Update if center moved significantly (>0.01 degrees) or size changed (>5%)
+      return centerDiff > 0.01 || sizeDiff > Math.max(newSize.lat, newSize.lng) * 0.05;
+    },
+    []
+  );
+
+  const map = useMap();
+
+  /**
+   * Update bounds with debouncing
+   */
+  const updateBounds = useCallback(
+    (immediate: boolean = false) => {
+      if (updateTimeoutRef.current) {
+        clearTimeout(updateTimeoutRef.current);
+      }
+
+      const update = () => {
+        if (isUpdatingRef.current) return;
+
+        const bounds = map.getBounds();
+        if (hasBoundsChanged(bounds, boundsRef.current)) {
+          boundsRef.current = bounds;
+          isUpdatingRef.current = true;
+
+          // Use requestAnimationFrame for smooth updates
+          requestAnimationFrame(() => {
+            setMapBounds(bounds);
+            // Reset flag after a short delay
+            setTimeout(() => {
+              isUpdatingRef.current = false;
+            }, 100);
+          });
+        }
+      };
+
+      if (immediate) {
+        update();
+      } else {
+        updateTimeoutRef.current = setTimeout(update, 300);
+      }
+    },
+    [map, setMapBounds, hasBoundsChanged]
+  );
+
+  useMapEvents({
+    moveend: () => {
+      updateBounds(false);
+    },
+    zoomend: () => {
+      // Faster update on zoom as it's a discrete action
+      updateBounds(false);
+    },
+    move: () => {
+      // Throttle during active movement to reduce updates
+      updateBounds(false);
+    },
+  });
+
+  // Initialize bounds on mount
+  useEffect(() => {
+    // Wait for map to be fully initialized
+    const timer = setTimeout(() => {
+      updateBounds(true);
+    }, 100);
+
+    return () => {
+      clearTimeout(timer);
+      if (updateTimeoutRef.current) {
+        clearTimeout(updateTimeoutRef.current);
+      }
+    };
+  }, [updateBounds]);
+
+  return null;
+};
+
+export default MapBoundsTracker;

bugulma/frontend/components/map/MapControls.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { useMap } from 'react-leaflet';
+import { useMapActions } from '@/contexts/MapContexts.tsx';
+import { RotateCw, ZoomIn, ZoomOut } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+
+// Bugulma center coordinates [lat, lng] for Leaflet
+const BUGULMA_CENTER: [number, number] = [54.5384152, 52.7955953];
+const DEFAULT_ZOOM = 12;
+
+const MapControls: React.FC = () => {
+  const map = useMap();
+  const { resetView } = useMapActions();
+
+  const handleZoomIn = () => {
+    map.zoomIn();
+  };
+
+  const handleZoomOut = () => {
+    map.zoomOut();
+  };
+
+  const handleReset = () => {
+    map.setView(BUGULMA_CENTER, DEFAULT_ZOOM, { animate: true });
+    resetView();
+  };
+
+  return (
+    <div className="absolute bottom-4 right-4 flex flex-col gap-2 z-50">
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={handleZoomIn}
+        className="h-10 w-10 p-0 shadow-md"
+        aria-label="Zoom in"
+      >
+        <ZoomIn className="h-4 h-5 text-current w-4 w-5" />
+      </Button>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={handleZoomOut}
+        className="h-10 w-10 p-0 shadow-md"
+        aria-label="Zoom out"
+      >
+        <ZoomOut className="h-4 h-5 text-current w-4 w-5" />
+      </Button>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={handleReset}
+        className="h-10 w-10 p-0 shadow-md"
+        aria-label="Reset view"
+      >
+        <RotateCw className="h-4 h-5 text-current w-4 w-5" />
+      </Button>
+    </div>
+  );
+};
+
+export default React.memo(MapControls);

bugulma/frontend/components/map/MapFilters.tsx

@@ -0,0 +1,94 @@
+import React from 'react';
+import { useMapFilter, useMapUI } from '@/contexts/MapContexts.tsx';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { useDynamicSectors } from '@/hooks/useDynamicSectors.ts';
+import { SortOption } from '@/types.ts';
+import { ArrowUpDown } from 'lucide-react';
+import Button from '@/components/ui/Button.tsx';
+import Checkbox from '@/components/ui/Checkbox.tsx';
+import Select from '@/components/ui/Select.tsx';
+import { Flex, Grid } from '@/components/ui/layout';
+
+const MapFilters: React.FC = () => {
+  const { t } = useTranslation();
+  const { sectors: availableSectors, isLoading: sectorsLoading } = useDynamicSectors(20); // Get more sectors for filtering
+  const { selectedSectors, sortOption } = useMapFilter();
+  const { mapViewMode } = useMapUI();
+  const { handleSectorChange, setSortOption } = useMapFilter();
+  const { setMapViewMode } = useMapUI();
+
+  return (
+    <div className="p-4 border-b">
+      <Flex
+        role="tablist"
+        aria-label="Map view mode"
+        justify="around"
+        className="mb-4 bg-muted p-1 rounded-lg"
+      >
+        <Button
+          role="tab"
+          aria-selected={mapViewMode === 'organizations'}
+          variant={mapViewMode === 'organizations' ? 'primary' : 'ghost'}
+          size="sm"
+          onClick={() => setMapViewMode('organizations')}
+          className="flex-1"
+        >
+          {t('mapSidebar.organizationsTab')}
+        </Button>
+        <Button
+          role="tab"
+          aria-selected={mapViewMode === 'historical'}
+          variant={mapViewMode === 'historical' ? 'primary' : 'ghost'}
+          size="sm"
+          onClick={() => setMapViewMode('historical')}
+          className="flex-1"
+        >
+          {t('mapSidebar.historicalTab')}
+        </Button>
+      </Flex>
+
+      {mapViewMode === 'organizations' && (
+        <>
+          <h3 className="text-sm font-semibold mb-2">{t('mapSidebar.filters.title')}</h3>
+          <Grid cols={2} gap="xs" className="mb-4">
+            {sectorsLoading ? (
+              // Loading state for sectors
+              Array.from({ length: 8 }, (_, i) => (
+                <div key={i} className="animate-pulse h-5 bg-muted rounded"></div>
+              ))
+            ) : (
+              availableSectors.map((sector) => (
+                <label key={sector.backendName} className="flex items-center gap-2 text-sm">
+                  <Checkbox
+                    id={`sector-${sector.backendName}`}
+                    name={`sector-${sector.backendName}`}
+                    checked={selectedSectors.includes(sector.backendName)}
+                    onChange={() => handleSectorChange(sector.backendName)}
+                  />
+                  {t(sector.nameKey)}
+                </label>
+              ))
+            )}
+          </Grid>
+          <div className="relative">
+            <ArrowUpDown className="-translate-y-1/2 absolute h-4 left-3 text-current text-muted-foreground top-1/2 w-4" />
+            <Select
+              id="map-sort-select"
+              name="sortOption"
+              value={sortOption}
+              onChange={(e) => setSortOption(e.target.value as SortOption)}
+              className="pl-9"
+            >
+              <option value="name_asc">{t('mapSidebar.sort.name_asc')}</option>
+              <option value="name_desc">{t('mapSidebar.sort.name_desc')}</option>
+              <option value="size_desc">{t('mapSidebar.sort.size_desc')}</option>
+              <option value="size_asc">{t('mapSidebar.sort.size_asc')}</option>
+            </Select>
+          </div>
+        </>
+      )}
+    </div>
+  );
+};
+
+export default React.memo(MapFilters);

bugulma/frontend/components/map/MapHeader.tsx

@@ -0,0 +1,88 @@
+import React, { useCallback } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useMapActions, useMapFilter, useMapUI } from '@/contexts/MapContexts.tsx';
+import { useHeaderSearch } from '@/hooks/useHeaderSearch.ts';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import { ChevronDown } from 'lucide-react';
+import BrandIdentity from '@/components/layout/BrandIdentity.tsx';
+import { HeaderLayout, HeaderSection } from '@/components/layout/Header.tsx';
+import HeaderActions from '@/components/layout/HeaderActions.tsx';
+import Button from '@/components/ui/Button.tsx';
+import IconButton from '@/components/ui/IconButton.tsx';
+import SearchBar from '@/components/ui/SearchBar.tsx';
+import SearchSuggestions from '@/components/map/SearchSuggestions.tsx';
+
+
+const MapHeader = () => {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const { searchTerm, searchSuggestions, isSuggesting, isBackendSearching, searchError, clearSearch } = useMapFilter();
+  const { isSidebarOpen, addOrgButtonRef } = useMapUI();
+  const { setSearchTerm } = useMapFilter();
+  const { setIsSidebarOpen } = useMapUI();
+  const { handleAddOrganization } = useMapActions();
+
+  const { handleSearchSubmit } = useHeaderSearch({
+    initialValue: searchTerm,
+    enableIRIHandling: true,
+    onSearchChange: setSearchTerm
+  });
+
+  const handleSearchChange = useCallback((value: string) => {
+    setSearchTerm(value);
+  }, [setSearchTerm]);
+
+  return (
+    <HeaderLayout>
+      <HeaderSection>
+        <IconButton
+          variant={isSidebarOpen ? 'secondary' : 'ghost'}
+          size="sm"
+          onClick={() => setIsSidebarOpen(!isSidebarOpen)}
+          aria-label={isSidebarOpen ? 'Close sidebar' : 'Open sidebar'}
+          aria-expanded={isSidebarOpen}
+          aria-controls="map-sidebar"
+          className="transition-all duration-200 hover:bg-accent"
+          title={isSidebarOpen ? 'Close sidebar' : 'Open sidebar'}
+        >
+          <ChevronDown className={`h-5 w-5 transition-transform duration-200 ${
+              isSidebarOpen ? 'rotate-90' : '-rotate-90'
+            }`} />
+        </IconButton>
+        <BrandIdentity onClick={() => navigate('/')} />
+      </HeaderSection>
+
+      <HeaderSection align="center" className="order-3 md:order-2">
+        <div className="w-full md:w-auto md:flex-1 max-w-md relative">
+          <SearchBar
+            value={searchTerm}
+            onChange={handleSearchChange}
+            onSubmit={handleSearchSubmit}
+            showClearButton={true}
+            onClear={clearSearch}
+            containerClassName="w-full"
+          />
+          <SearchSuggestions
+            suggestions={searchSuggestions}
+            isLoading={isSuggesting || isBackendSearching}
+            error={searchError}
+            searchTerm={searchTerm}
+            onSelect={(suggestion) => {
+              setSearchTerm(suggestion);
+              handleSearchSubmit(suggestion);
+            }}
+          />
+        </div>
+      </HeaderSection>
+
+      <HeaderSection align="right" className="order-2 md:order-3 gap-2">
+        <Button ref={addOrgButtonRef} onClick={handleAddOrganization} size="sm">
+          {t('mapHeader.addButton')}
+        </Button>
+        <HeaderActions showThemeToggle={false} showAuthButton={false} />
+      </HeaderSection>
+    </HeaderLayout>
+  );
+};
+
+export default React.memo(MapHeader);

bugulma/frontend/components/map/MapSidebar.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { useTranslation } from '@/hooks/useI18n.tsx';
+import Button from '@/components/ui/Button.tsx';
+import MapFilters from '@/components/map/MapFilters.tsx';
+import SidebarContent from '@/components/map/SidebarContent.tsx';
+import { useMapUI, useMapInteraction, useMapActions } from '@/contexts/MapContexts.tsx';
+import { ArrowLeft } from 'lucide-react';
+
+const MapSidebar = () => {
+  const { t } = useTranslation();
+  const { isSidebarOpen } = useMapUI();
+  const { selectedOrg, selectedLandmark } = useMapInteraction();
+  const { handleSelectOrg, handleSelectLandmark } = useMapActions();
+
+  const sidebarClasses = `
+        bg-background border-r flex flex-col
+        fixed md:relative inset-y-0 left-0 z-30
+        w-full max-w-[calc(100%-2rem)] sm:max-w-sm
+        transition-transform duration-300 ease-in-out md:transition-[width]
+        ${isSidebarOpen ? 'translate-x-0' : '-translate-x-full'}
+        md:transform-none md:min-w-0 md:shrink-0
+        ${isSidebarOpen ? 'md:w-96' : 'md:w-0 md:border-r-0 md:overflow-hidden'}
+    `;
+
+  return (
+    <aside id="map-sidebar" className={sidebarClasses}>
+      {/* Wrapper to contain content and handle overflow, especially for w-0 state */}
+      <div
+        className={`w-full h-full flex flex-col overflow-hidden ${isSidebarOpen ? 'md:w-96' : 'md:w-0 md:pointer-events-none'}`}
+      >
+        {!selectedOrg && !selectedLandmark ? (
+          <MapFilters />
+        ) : (
+          <div className="p-4 border-b">
+            <Button
+              variant="outline"
+              onClick={() => {
+                handleSelectOrg(null);
+                handleSelectLandmark(null);
+              }}
+            >
+              <ArrowLeft className="h-4 mr-2 text-current w-4" />
+              {t('mapSidebar.backToList')}
+            </Button>
+          </div>
+        )}
+
+        {/* Content */}
+        <SidebarContent />
+      </div>
+    </aside>
+  );
+};
+
+export default React.memo(MapSidebar);

bugulma/frontend/components/map/MatchLines.tsx

@@ -0,0 +1,179 @@
+import { LatLngTuple } from 'leaflet';
+import React, { useMemo } from 'react';
+import { Polyline, Popup } from 'react-leaflet';
+import { useTranslation } from '@/hooks/useI18n';
+import type { BackendMatch } from '@/schemas/backend/match';
+
+interface MatchLinesProps {
+  matches: BackendMatch[];
+  selectedMatchId: string | null;
+  onMatchSelect: (matchId: string) => void;
+}
+
+/**
+ * Individual match line component memoized to prevent unnecessary re-renders
+ */
+const MatchLine = React.memo<{
+  match: BackendMatch;
+  positions: LatLngTuple[];
+  isSelected: boolean;
+  onClick: () => void;
+}>(({ match, positions, isSelected, onClick }) => {
+  const { t } = useTranslation();
+
+  const getLineColor = () => {
+    switch (match.Status) {
+      case 'live':
+        return 'hsl(var(--primary))';
+      case 'contracted':
+        return 'hsl(var(--success))';
+      case 'negotiating':
+        return 'hsl(var(--warning))';
+      case 'reserved':
+        return 'hsl(var(--secondary))';
+      default:
+        return 'hsl(var(--muted-foreground))';
+    }
+  };
+
+  const formatScore = (score: number) => {
+    return `${(score * 100).toFixed(1)}%`;
+  };
+
+  const formatCurrency = (value: number) => {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'EUR',
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 0,
+    }).format(value);
+  };
+
+  return (
+    <Polyline
+      positions={positions}
+      pathOptions={{
+        color: getLineColor(),
+        weight: isSelected ? 5 : 3,
+        opacity: isSelected ? 1 : 0.7,
+        dashArray: match.Status === 'suggested' ? '5, 5' : undefined,
+      }}
+      eventHandlers={{
+        click: onClick,
+        mouseover: (e) => {
+          const layer = e.target;
+          layer.setStyle({
+            weight: isSelected ? 6 : 4,
+            opacity: 1,
+          });
+        },
+        mouseout: (e) => {
+          const layer = e.target;
+          layer.setStyle({
+            weight: isSelected ? 5 : 3,
+            opacity: isSelected ? 1 : 0.7,
+          });
+        },
+      }}
+    >
+      <Popup>
+        <div className="min-w-64">
+          <div className="flex items-center justify-between mb-2">
+            <h4 className="font-semibold text-sm">{t('matchesMap.matchConnection', 'Match Connection')}</h4>
+            <span className={`text-xs px-2 py-1 rounded ${
+              match.Status === 'live' ? 'bg-success/20 text-success' :
+              match.Status === 'contracted' ? 'bg-success/20 text-success' :
+              match.Status === 'negotiating' ? 'bg-warning/20 text-warning' :
+              'bg-muted text-muted-foreground'
+            }`}>
+              {t(`matchStatus.${match.Status}`, match.Status)}
+            </span>
+          </div>
+
+          <div className="space-y-2 text-sm">
+            <div className="grid grid-cols-2 gap-2">
+              <div>
+                <span className="text-muted-foreground">{t('matchesMap.compatibility', 'Compatibility')}:</span>
+                <div className="font-medium">{formatScore(match.CompatibilityScore)}</div>
+              </div>
+              <div>
+                <span className="text-muted-foreground">{t('matchesMap.distance', 'Distance')}:</span>
+                <div className="font-medium">{match.DistanceKm.toFixed(1)} km</div>
+              </div>
+            </div>
+
+            <div>
+              <span className="text-muted-foreground">{t('matchesMap.economicValue', 'Economic Value')}:</span>
+              <div className="font-medium text-success">{formatCurrency(match.EconomicValue)}</div>
+            </div>
+
+            {match.EconomicImpact?.annual_savings && (
+              <div>
+                <span className="text-muted-foreground">{t('matchesMap.annualSavings', 'Annual Savings')}:</span>
+                <div className="font-medium text-success">
+                  {formatCurrency(match.EconomicImpact.annual_savings)}
+                </div>
+              </div>
+            )}
+          </div>
+
+          <button
+            onClick={onClick}
+            className="mt-3 w-full px-3 py-2 bg-primary text-primary-foreground rounded text-sm font-medium hover:bg-primary/90 transition-colors"
+          >
+            {t('matchesMap.viewDetails', 'View Details')}
+          </button>
+        </div>
+      </Popup>
+    </Polyline>
+  );
+});
+
+MatchLine.displayName = 'MatchLine';
+
+const MatchLines: React.FC<MatchLinesProps> = ({ matches, selectedMatchId, onMatchSelect }) => {
+  // Transform matches into line data with positions
+  const matchLines = useMemo(() => {
+    return matches
+      .map(match => {
+        // For now, we'll need to get site coordinates from the match data
+        // In a real implementation, we'd join with site data
+        // For now, creating mock positions based on match ID for demonstration
+        const baseLat = 55.1644; // Bugulma center
+        const baseLng = 50.2050;
+
+        // Generate pseudo-random but consistent positions based on match ID
+        const hash = match.ID.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0);
+        const lat1 = baseLat + (hash % 100 - 50) * 0.01;
+        const lng1 = baseLng + ((hash * 7) % 100 - 50) * 0.01;
+        const lat2 = baseLat + ((hash * 13) % 100 - 50) * 0.01;
+        const lng2 = baseLng + ((hash * 17) % 100 - 50) * 0.01;
+
+        return {
+          match,
+          positions: [
+            [lat1, lng1] as LatLngTuple,
+            [lat2, lng2] as LatLngTuple,
+          ],
+          isSelected: match.ID === selectedMatchId,
+        };
+      })
+      .filter(line => line.positions.length === 2);
+  }, [matches, selectedMatchId]);
+
+  return (
+    <>
+      {matchLines.map(({ match, positions, isSelected }) => (
+        <MatchLine
+          key={match.ID}
+          match={match}
+          positions={positions}
+          isSelected={isSelected}
+          onClick={() => onMatchSelect(match.ID)}
+        />
+      ))}
+    </>
+  );
+};
+
+export default React.memo(MatchLines);

bugulma/frontend/components/map/MatchesMap.tsx

@@ -0,0 +1,207 @@
+import L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+import React, { useCallback, useEffect, useRef } from 'react';
+import { GeoJSON, MapContainer, TileLayer, useMap, useMapEvents } from 'react-leaflet';
+import MarkerClusterGroup from 'react-leaflet-markercluster';
+import 'react-leaflet-markercluster/styles';
+import {
+  useMapInteraction,
+  useMapUI,
+  useMapViewport,
+} from '@/contexts/MapContexts.tsx';
+import bugulmaGeo from '@/data/bugulmaGeometry.json';
+import { useMapData } from '@/hooks/map/useMapData.ts';
+import MapControls from '@/components/map/MapControls.tsx';
+import MatchLines from '@/components/map/MatchLines.tsx';
+import ResourceFlowMarkers from '@/components/map/ResourceFlowMarkers.tsx';
+import type { BackendMatch } from '@/schemas/backend/match';
+
+// Fix for default marker icon issue in Leaflet with webpack/vite
+delete (L.Icon.Default.prototype as unknown as { _getIconUrl?: unknown })._getIconUrl;
+L.Icon.Default.mergeOptions({
+  iconRetinaUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-icon-2x.png',
+  iconUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-icon.png',
+  shadowUrl: 'https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/images/marker-shadow.png',
+});
+
+interface MatchesMapProps {
+  matches: BackendMatch[];
+  selectedMatchId: string | null;
+  onMatchSelect: (matchId: string) => void;
+}
+
+/**
+ * Component to handle map resize when sidebar opens/closes
+ */
+const MapResizeHandler = () => {
+  const map = useMap();
+  const { isSidebarOpen } = useMapUI();
+  const resizeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    // Clear any pending resize
+    if (resizeTimeoutRef.current) {
+      clearTimeout(resizeTimeoutRef.current);
+    }
+
+    // Delay resize to allow CSS transition to complete
+    resizeTimeoutRef.current = setTimeout(() => {
+      map.invalidateSize();
+    }, 350);
+
+    return () => {
+      if (resizeTimeoutRef.current) {
+        clearTimeout(resizeTimeoutRef.current);
+      }
+    };
+  }, [map, isSidebarOpen]);
+
+  return null;
+};
+
+/**
+ * Component to sync Leaflet map view with context state
+ */
+const MapSync = () => {
+  const { mapCenter, zoom, setZoom, setMapCenter } = useMapViewport();
+  const map = useMap();
+  const isUpdatingRef = useRef(false);
+  const lastUpdateRef = useRef<{ center: [number, number]; zoom: number } | null>(null);
+
+  // Sync context state to map
+  useEffect(() => {
+    if (isUpdatingRef.current) return;
+
+    const currentCenter = map.getCenter();
+    const centerDiff =
+      Math.abs(currentCenter.lat - mapCenter[0]) + Math.abs(currentCenter.lng - mapCenter[1]);
+    const zoomDiff = Math.abs(map.getZoom() - zoom);
+
+    const shouldUpdate = zoomDiff > 0.1 || centerDiff > 0.0001 || !lastUpdateRef.current;
+
+    if (shouldUpdate) {
+      const lastUpdate = lastUpdateRef.current;
+      if (
+        lastUpdate &&
+        lastUpdate.center[0] === mapCenter[0] &&
+        lastUpdate.center[1] === mapCenter[1] &&
+        lastUpdate.zoom === zoom
+      ) {
+        return;
+      }
+
+      isUpdatingRef.current = true;
+      map.setView(mapCenter, zoom, { animate: true });
+      lastUpdateRef.current = { center: mapCenter, zoom };
+
+      const timeoutId = setTimeout(() => {
+        isUpdatingRef.current = false;
+      }, 300);
+
+      return () => clearTimeout(timeoutId);
+    }
+  }, [map, mapCenter, zoom]);
+
+  // Sync map state to context
+  const mapEvents = useMapEvents({
+    moveend: () => {
+      if (!isUpdatingRef.current) {
+        const center = mapEvents.getCenter();
+        setMapCenter([center.lat, center.lng]);
+      }
+    },
+    zoomend: () => {
+      if (!isUpdatingRef.current) {
+        setZoom(mapEvents.getZoom());
+      }
+    },
+  });
+
+  return null;
+};
+
+const MatchesMap: React.FC<MatchesMapProps> = ({ matches, selectedMatchId, onMatchSelect }) => {
+  const { mapCenter, zoom } = useMapViewport();
+  const { mapViewMode } = useMapUI();
+  const { organizations, historicalLandmarks } = useMapData();
+
+  const whenCreated = useCallback((map: L.Map) => {
+    // Fit bounds to Bugulma area on initial load
+    if (bugulmaGeo) {
+      const bounds = L.geoJSON(bugulmaGeo as any).getBounds();
+      map.fitBounds(bounds, { padding: [20, 20] });
+    }
+  }, []);
+
+  // GeoJSON styling for city boundary
+  const geoJsonStyle = {
+    color: 'hsl(var(--primary))',
+    weight: 1.5,
+    opacity: 0.8,
+    fillOpacity: 0.1,
+  };
+
+  return (
+    <MapContainer
+      center={mapCenter}
+      zoom={zoom}
+      minZoom={10}
+      maxZoom={18}
+      zoomControl={true}
+      scrollWheelZoom={true}
+      attributionControl={false}
+      className="bg-background h-full w-full"
+      preferCanvas={true}
+      fadeAnimation={true}
+      zoomAnimation={true}
+      zoomAnimationThreshold={4}
+      whenCreated={whenCreated}
+    >
+      <MapSync />
+      <MapResizeHandler />
+
+      {/* Map tile layer */}
+      <TileLayer
+        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
+        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+      />
+
+      {/* City boundary GeoJSON */}
+      {bugulmaGeo && (
+        <GeoJSON
+          data={bugulmaGeo as Parameters<typeof GeoJSON>[0]['data']}
+          style={geoJsonStyle}
+          onEachFeature={(feature, layer) => {
+            layer.on({
+              mouseover: () => {
+                layer.setStyle({ weight: 2, opacity: 1 });
+              },
+              mouseout: () => {
+                layer.setStyle({ weight: 1.5, opacity: 0.8 });
+              },
+            });
+          }}
+        />
+      )}
+
+      {/* Match connection lines */}
+      <MatchLines
+        matches={matches}
+        selectedMatchId={selectedMatchId}
+        onMatchSelect={onMatchSelect}
+      />
+
+      {/* Resource flow markers */}
+      <ResourceFlowMarkers
+        matches={matches}
+        selectedMatchId={selectedMatchId}
+        onMatchSelect={onMatchSelect}
+      />
+
+      {/* Map controls */}
+      <MapControls />
+    </MapContainer>
+  );
+};
+
+export default React.memo(MatchesMap);

bugulma/frontend/components/map/OrganizationCenterHandler.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useRef } from 'react';
+import { useMap } from 'react-leaflet';
+import { useMapInteraction, useMapViewport } from '@/contexts/MapContexts.tsx';
+import { useOrganizationSites } from '@/hooks/map/useOrganizationSites.ts';
+
+/**
+ * Component to handle centering map on selected organization
+ * This runs inside MapContainer to access the Leaflet map instance
+ * Optimized to prevent unnecessary updates and infinite loops
+ */
+const OrganizationCenterHandler = () => {
+  const map = useMap();
+  const { selectedOrg } = useMapInteraction();
+  const { setMapCenter, setZoom } = useMapViewport();
+  const { orgSitesMap } = useOrganizationSites(selectedOrg ? [selectedOrg] : []);
+  const lastCenteredOrgIdRef = useRef<string | null>(null);
+  const isCenteringRef = useRef(false);
+
+  useEffect(() => {
+    if (!selectedOrg) {
+      lastCenteredOrgIdRef.current = null;
+      return;
+    }
+
+    // Prevent re-centering if we already centered on this org
+    if (lastCenteredOrgIdRef.current === selectedOrg.ID) {
+      return;
+    }
+
+    // Prevent updates during centering animation
+    if (isCenteringRef.current) {
+      return;
+    }
+
+    const site = orgSitesMap.get(selectedOrg.ID);
+    if (site) {
+      const position: [number, number] = [site.Latitude, site.Longitude];
+      const currentCenter = map.getCenter();
+      const currentZoom = map.getZoom();
+
+      // Only center if we're not already close to this position
+      const centerDiff =
+        Math.abs(currentCenter.lat - position[0]) + Math.abs(currentCenter.lng - position[1]);
+      const zoomDiff = Math.abs(currentZoom - 14);
+
+      if (centerDiff > 0.001 || zoomDiff > 0.5) {
+        isCenteringRef.current = true;
+        lastCenteredOrgIdRef.current = selectedOrg.ID;
+
+        map.setView(position, 14, { animate: true });
+        setMapCenter(position);
+        setZoom(14);
+
+        // Reset flag after animation completes
+        const timeoutId = setTimeout(() => {
+          isCenteringRef.current = false;
+        }, 500);
+
+        return () => {
+          clearTimeout(timeoutId);
+        };
+      }
+    }
+  }, [selectedOrg, orgSitesMap, map, setMapCenter, setZoom]);
+
+  return null;
+};
+
+export default OrganizationCenterHandler;

bugulma/frontend/components/map/OrganizationListItem.tsx

@@ -0,0 +1,116 @@
+import React, { useCallback } from 'react';
+import { getSectorDisplay } from '@/constants.tsx';
+import { mapBackendSectorToTranslationKey } from '@/lib/sector-mapper.ts';
+import { getOrganizationSubtypeLabel } from '@/schemas/organizationSubtype.ts';
+import { Organization } from '@/types.ts';
+import { BadgeCheck } from 'lucide-react';
+import Badge from '@/components/ui/Badge.tsx';
+import HighlightedText from '@/components/ui/HighlightedText.tsx';
+
+interface OrganizationListItemProps {
+  org: Organization;
+  isSelected: boolean;
+  onSelectOrg: (org: Organization) => void;
+  onHoverOrg: (id: string | null) => void;
+  searchTerm: string;
+}
+
+const OrganizationListItem: React.FC<OrganizationListItemProps> = React.memo(
+  ({ org, isSelected, onSelectOrg, onHoverOrg, searchTerm }) => {
+    const sectorDisplay = getSectorDisplay(org.Sector);
+
+    const baseClasses =
+      'group rounded-xl cursor-pointer transition-all duration-300 ease-out border border-border/50 shadow-sm hover:shadow-md';
+    const stateClasses = isSelected
+      ? 'bg-primary/10 border-primary shadow-md ring-2 ring-primary/20'
+      : 'bg-card/50 hover:bg-card hover:border-border';
+
+    const handleClick = useCallback(() => onSelectOrg(org), [onSelectOrg, org]);
+    const handleMouseEnter = useCallback(() => onHoverOrg(org.ID), [onHoverOrg, org.ID]);
+    const handleMouseLeave = useCallback(() => onHoverOrg(null), [onHoverOrg]);
+
+    return (
+      <div
+        onClick={handleClick}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        className={`${baseClasses} ${stateClasses} p-4`}
+        role="button"
+        aria-pressed={isSelected}
+        tabIndex={0}
+        onKeyDown={(e) => (e.key === 'Enter' || e.key === ' ') && onSelectOrg(org)}
+      >
+        <div className="flex items-start gap-4">
+          {/* Enhanced Icon Container */}
+          <div className="h-14 w-14 rounded-xl flex items-center justify-center shrink-0 bg-gradient-to-br from-muted/80 to-muted/40 overflow-hidden border border-border/50 shadow-sm group-hover:shadow-md transition-shadow duration-300">
+            {org.LogoURL ? (
+              <img
+                src={org.LogoURL}
+                alt={`${org.Name} logo`}
+                className="w-full h-full object-cover"
+                loading="lazy"
+                decoding="async"
+                onError={(e) => {
+                  (e.target as HTMLImageElement).style.display = 'none';
+                }}
+              />
+            ) : (
+              sector ? (
+                <div
+                  className="w-full h-full flex items-center justify-center"
+                  style={{
+                    backgroundColor: `hsl(var(--sector-${sectorDisplay.colorKey}))`,
+                  }}
+                >
+                  {React.cloneElement(sectorDisplay.icon, {
+                    className: 'h-7 w-7 text-white drop-shadow-sm',
+                  })}
+                </div>
+              ) : (
+                <div className="w-full h-full flex items-center justify-center bg-gradient-to-br from-primary/20 to-primary/10">
+                  <span className="text-xl font-bold text-primary/50">{org.Name.charAt(0).toUpperCase()}</span>
+                </div>
+              )
+            )}
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 min-w-0">
+            {/* Name and Verified Badge */}
+            <div className="flex items-start gap-2 mb-2">
+              <h3 className="font-semibold text-base leading-tight text-foreground group-hover:text-primary transition-colors duration-200 flex-1">
+                <HighlightedText text={org.Name} highlight={searchTerm} />
+              </h3>
+              {org.Verified && (
+                <BadgeCheck className="h-4 mt-0.5 shrink-0 text-current text-success-DEFAULT w-4" />
+              )}
+            </div>
+
+            {/* Subtype Badge */}
+            {org.Subtype && (
+              <div className="mb-2">
+                <Badge
+                  variant="secondary"
+                  className="text-xs font-medium px-2.5 py-0.5 bg-primary/10 text-primary border border-primary/20"
+                >
+                  {getOrganizationSubtypeLabel(org.Subtype)}
+                </Badge>
+              </div>
+            )}
+
+            {/* Description */}
+            {org.Description && (
+              <p className="text-sm text-muted-foreground leading-relaxed line-clamp-2 group-hover:text-foreground/80 transition-colors duration-200">
+                <HighlightedText text={org.Description} highlight={searchTerm} />
+              </p>
+            )}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+OrganizationListItem.displayName = 'OrganizationListItem';
+
+export default OrganizationListItem;

bugulma/frontend/components/map/OrganizationMarkers.tsx

@@ -0,0 +1,190 @@
+import L, { LatLngTuple } from 'leaflet';
+import React, { useCallback, useMemo } from 'react';
+import { Marker, Popup } from 'react-leaflet';
+import { getSectorDisplay } from '@/constants.tsx';
+import { useMapActions, useMapInteraction } from '@/contexts/MapContexts.tsx';
+import { useOrganizationSites } from '@/hooks/map/useOrganizationSites.ts';
+import { mapBackendSectorToTranslationKey } from '@/lib/sector-mapper.ts';
+import { Organization } from '@/types.ts';
+import { getCachedOrganizationIcon } from '@/utils/map/iconCache.ts';
+
+interface OrganizationMarkersProps {
+  organizations: Organization[];
+  selectedOrg: Organization | null;
+  hoveredOrgId: string | null;
+}
+
+/**
+ * Individual marker component memoized to prevent unnecessary re-renders
+ */
+const OrganizationMarker = React.memo<{
+  org: Organization;
+  site: { Latitude: number; Longitude: number };
+  sector: { icon?: React.ReactElement; colorKey?: string } | null;
+  isSelected: boolean;
+  isHovered: boolean;
+  onSelect: (org: Organization) => void;
+  onHover: (orgId: string | null) => void;
+}>(({ org, site, sector, isSelected, isHovered, onSelect, onHover }) => {
+  const position: LatLngTuple = useMemo(
+    () => [site.Latitude, site.Longitude],
+    [site.Latitude, site.Longitude]
+  );
+
+  const icon = useMemo(
+    () => getCachedOrganizationIcon(org.ID, org, sector, isSelected, isHovered),
+    [org.ID, org, sector, isSelected, isHovered]
+  );
+
+  const handleClick = useCallback(() => {
+    onSelect(org);
+  }, [org, onSelect]);
+
+  const handleMouseOver = useCallback(() => {
+    onHover(org.ID);
+  }, [org.ID, onHover]);
+
+  const handleMouseOut = useCallback(() => {
+    onHover(null);
+  }, [onHover]);
+
+  // Don't render if coordinates are invalid
+  if (!site.Latitude || !site.Longitude || site.Latitude === 0 || site.Longitude === 0) {
+    return null;
+  }
+
+  return (
+    <Marker
+      position={position}
+      icon={icon}
+      zIndexOffset={isSelected ? 1000 : isHovered ? 500 : 0}
+      keyboard={true}
+      interactive={true}
+      riseOnHover={true}
+      eventHandlers={{
+        click: handleClick,
+        mouseover: handleMouseOver,
+        mouseout: handleMouseOut,
+      }}
+    >
+      <Popup closeButton={true} autoPan={true} maxWidth={300}>
+        <div className="p-1">
+          <h3 className="text-base font-semibold mb-1">{org.Name}</h3>
+          {org.Sector && (
+            <p className="text-sm text-muted-foreground">{org.Sector}</p>
+          )}
+          {org.Description && (
+            <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
+              {org.Description}
+            </p>
+          )}
+        </div>
+      </Popup>
+    </Marker>
+  );
+}, (prevProps, nextProps) => {
+  // Custom comparison function for React.memo
+  return (
+    prevProps.org.ID === nextProps.org.ID &&
+    prevProps.site.Latitude === nextProps.site.Latitude &&
+    prevProps.site.Longitude === nextProps.site.Longitude &&
+    prevProps.isSelected === nextProps.isSelected &&
+    prevProps.isHovered === nextProps.isHovered &&
+    prevProps.sector?.colorKey === nextProps.sector?.colorKey
+  );
+});
+
+OrganizationMarker.displayName = 'OrganizationMarker';
+
+const OrganizationMarkers: React.FC<OrganizationMarkersProps> = ({
+  organizations,
+  selectedOrg,
+  hoveredOrgId,
+}) => {
+  const { handleSelectOrg } = useMapActions();
+  const { setHoveredOrgId } = useMapInteraction();
+  const { orgSitesMap } = useOrganizationSites(organizations);
+
+  // No need for sector map - using getSectorDisplay directly
+
+  // Filter organizations that have valid coordinates (from site or organization)
+  const organizationsWithCoordinates = useMemo(() => {
+    const result = organizations
+      .filter((org) => org.ID && org.ID.trim() !== '')
+      .map((org) => {
+        const site = orgSitesMap.get(org.ID);
+
+        // Use site coordinates if available and valid
+        if (site && site.Latitude && site.Longitude && site.Latitude !== 0 && site.Longitude !== 0) {
+          return { org, site };
+        }
+
+        // Fallback to organization coordinates if available and valid
+        if (org.Latitude && org.Longitude && org.Latitude !== 0 && org.Longitude !== 0) {
+          return { org, site: { Latitude: org.Latitude, Longitude: org.Longitude } };
+        }
+
+        return null;
+      })
+      .filter(
+        (item): item is { org: Organization; site: { Latitude: number; Longitude: number } } =>
+          item !== null
+      );
+
+    return result;
+  }, [organizations, orgSitesMap]);
+
+  // Debug: Log marker count and details in development
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[OrganizationMarkers] Rendering ${organizationsWithCoordinates.length} markers`, {
+      totalOrganizations: organizations.length,
+      withCoordinates: organizationsWithCoordinates.length,
+      organizationsSample: organizations.slice(0, 3).map(org => ({
+        id: org.ID,
+        name: org.Name,
+        coords: [org.Latitude || 0, org.Longitude || 0],
+      })),
+      sample: organizationsWithCoordinates.slice(0, 3).map(({ org, site }) => ({
+        name: org.Name,
+        coords: site ? [site.Latitude, site.Longitude] : null,
+        hasLogo: !!org.LogoURL,
+      })),
+    });
+
+    // Additional debug info
+    if (organizations.length === 0) {
+      console.warn('[OrganizationMarkers] No organizations received! Check API connection and data flow.');
+    }
+  }
+
+  return (
+    <>
+      {organizationsWithCoordinates.map(({ org, site }) => {
+        const sectorDisplay = getSectorDisplay(org.Sector);
+
+        const isSelected = selectedOrg?.ID === org.ID;
+        const isHovered = hoveredOrgId === org.ID;
+
+        // Skip rendering if coordinates are invalid
+        if (!site.Latitude || !site.Longitude || site.Latitude === 0 || site.Longitude === 0) {
+          return null;
+        }
+
+        return (
+          <OrganizationMarker
+            key={`${org.ID}-${site.Latitude.toFixed(6)}-${site.Longitude.toFixed(6)}`}
+            org={org}
+            site={site}
+            sector={sectorDisplay}
+            isSelected={isSelected}
+            isHovered={isHovered}
+            onSelect={handleSelectOrg}
+            onHover={setHoveredOrgId}
+          />
+        );
+      })}
+    </>
+  );
+};
+
+export default React.memo(OrganizationMarkers);