Project Structure

Root Directory

core/
├── .env.example          # Environment variables template
├── .env.local            # Local environment configuration (gitignored)
├── .gitignore            # Git ignore rules
├── components.json       # shadcn/ui configuration
├── eslint.config.mjs     # ESLint configuration
├── next.config.ts        # Next.js configuration
├── package.json          # Dependencies and scripts
├── postcss.config.mjs    # PostCSS configuration
├── tsconfig.json         # TypeScript configuration
├── public/               # Static assets
└── src/                  # Source code

---

Source Directory (/src)

src/
├── app/                  # Next.js App Router pages
├── components/           # Reusable UI components
├── config/               # Application configuration
├── docs/                 # Documentation (you are here)
├── hooks/                # Custom React hooks
└── lib/                  # Libraries and services

---

App Directory (/src/app)

Route Groups

app/
├── (auth)/                         # Authentication routes (public)
│   ├── sign-in/
│   │   └── page.tsx                # Login page
│   └── sign-up/
│       └── page.tsx                # Registration page
│
├── (core)/                         # Protected application routes
│   ├── layout.tsx                  # Shared layout with sidebar
│   ├── account/
│   │   └── page.tsx                # User account settings
│   ├── adaptive-optimizers/
│   │   ├── page.tsx                # Adaptive optimizer main page
│   │   ├── components/             # Feature-specific components
│   │   │   ├── chart-display.tsx
│   │   │   ├── control-panel.tsx
│   │   │   ├── parameter-sliders.tsx
│   │   │   ├── results-panel.tsx
│   │   │   ├── scenario-selector.tsx
│   │   │   ├── simulation-chart.tsx
│   │   │   └── status-indicator.tsx
│   │   └── utils/                  # Feature-specific utilities
│   │       ├── scenarios.ts
│   │       ├── simulation.ts
│   │       └── types.ts
│   ├── cad-integration/
│   │   ├── page.tsx                # CAD integration main page
│   │   └── components/             # 3D visualization components
│   ├── dashboard/
│   │   └── page.tsx                # Main dashboard
│   ├── history/
│   │   ├── page.tsx                # Reports history list
│   │   └── [id]/
│   │       └── page.tsx            # Individual report detail
│   ├── prediction-model/
│   │   └── page.tsx                # Reusability prediction
│   ├── reports/
│   │   └── page.tsx                # Reports management
│   ├── treatment-model/
│   │   └── page.tsx                # Treatment recommendations
│   ├── twin-engine/
│   │   ├── page.tsx                # Combined analysis
│   │   └── components/             # Twin engine components
│   └── websocket-monitor/
│       ├── page.tsx                # WebSocket monitoring page
│       └── components/             # Real-time monitoring components
│
├── api/                            # API routes
│   └── blockchain/
│       ├── status/
│       │   └── route.ts            # GET blockchain status
│       ├── store/
│       │   └── route.ts            # POST store report hash
│       └── verify/
│           └── route.ts            # POST verify report hash
│
├── api-demo/                       # API demo/testing page
│   └── page.tsx
│
├── globals.css                     # Global styles
├── layout.tsx                      # Root layout
├── page.tsx                        # Landing page
└── favicon.ico                     # App favicon

---

Components Directory (/src/components)

components/
├── index.ts                        # Barrel export
│
├── animation/                      # Animation components (Motion/Framer)
│   ├── blur-in-view.tsx            # Scroll-triggered blur animation
│   ├── blur-text.tsx               # Per-word/character blur text
│   ├── fuzzy-text.tsx              # Fuzzy/glitch text effect
│   ├── glass-surface.tsx           # Glassmorphism surface
│   ├── hover-follow-component.tsx  # Cursor-following component
│   ├── hover-follow-image.tsx      # Cursor-following image
│   ├── infinite-marquee.tsx        # Continuous scrolling marquee
│   ├── magnet-3d-card.tsx          # 3D hover effect card
│   └── proximity-text.tsx          # Cursor proximity text effect
│
├── auth/                           # Authentication components
│   ├── sign-in-form.tsx            # Login form
│   └── sign-up-form.tsx            # Registration form
│
├── blockchain/                     # Blockchain-related components
│   ├── blockchain-badge.tsx        # Verification badge
│   ├── blockchain-status.tsx       # Status display card
│   ├── index.ts                    # Barrel export
│   └── verify-dialog.tsx           # Verification dialog
│
├── charts/                         # Chart components
│   └── quality-chart.tsx           # Water quality visualization
│
├── feedback/                       # Feedback components
│   ├── index.ts
│   └── toaster.tsx                 # Toast notification container
│
├── forms/                          # Form components
│   ├── index.ts
│   ├── input-field.tsx             # Styled input with label
│   ├── select-field.tsx            # Styled select with label
│   └── status-badge.tsx            # Status indicator badge
│
├── home/                           # Landing page components
│   ├── index.ts                    # Barrel export
│   ├── background.tsx              # Animated backgrounds
│   ├── droplet-scene.tsx           # 3D droplet animation
│   ├── hero-text.tsx               # Hero section text
│   ├── timeline.tsx                # Process timeline
│   ├── water-webgl.tsx             # WebGL water effect
│   └── data/                       # Static data for landing page
│
├── layout/                         # Layout components
│   ├── footer.tsx                  # Footer component
│   ├── header.tsx                  # Header component
│   └── index.ts
│
├── sidebar/                        # Sidebar navigation
│   ├── app-sidebar.tsx             # Main sidebar component
│   ├── nav-main.tsx                # Main navigation items
│   ├── nav-projects.tsx            # Projects navigation
│   ├── nav-user.tsx                # User profile dropdown
│   └── team-switcher.tsx           # Team/org switcher
│
├── ui/                             # Base UI components (shadcn/ui)
│   ├── avatar.tsx
│   ├── badge.tsx
│   ├── breadcrumb.tsx
│   ├── button.tsx
│   ├── card.tsx
│   ├── chart.tsx
│   ├── collapsible.tsx
│   ├── dropdown-menu.tsx
│   ├── field.tsx
│   ├── form.tsx
│   ├── input.tsx
│   ├── label.tsx
│   ├── select.tsx
│   ├── separator.tsx
│   ├── sheet.tsx
│   ├── sidebar.tsx
│   ├── skeleton.tsx
│   ├── sonner.tsx
│   ├── spinner.tsx
│   ├── table.tsx
│   └── tooltip.tsx
│
└── water-recovery/                 # Water recovery components
    └── WaterRecoveryCard.tsx       # Recovery calculation card

---

Hooks Directory (/src/hooks)

hooks/
├── index.ts                        # Barrel export
├── use-blockchain.ts               # Blockchain operations hook
├── use-mobile.ts                   # Mobile detection hook
└── use-toast.ts                    # Toast notifications hook

---

Library Directory (/src/lib)

lib/
├── auth-context.tsx                # Authentication context provider
├── firebase.ts                     # Firebase initialization
├── utils.ts                        # General utilities
├── water-recovery.ts               # Water recovery calculations
│
├── blockchain/                     # Blockchain integration
│   ├── config.ts                   # Blockchain configuration
│   ├── hash.ts                     # Hashing utilities
│   ├── index.ts                    # Barrel export
│   ├── service.ts                  # BlockchainService class
│   └── types.ts                    # TypeScript interfaces
│
├── cad-integration/                # CAD integration utilities
│   ├── index.ts                    # Barrel export
│   ├── types.ts                    # CAD type definitions
│   └── utils.ts                    # CAD utility functions
│
├── email/                          # Email service (Resend)
│   ├── index.ts                    # Barrel export
│   ├── templates/                  # Email templates
│   └── service.ts                  # Email sending service
│
├── ml-api/                         # ML API client
│   ├── README.md                   # API documentation
│   ├── client.ts                   # MLAPIClient class
│   ├── hooks.ts                    # React hooks for API
│   ├── index.ts                    # Barrel export
│   └── types.ts                    # TypeScript interfaces
│
├── pdf/                            # PDF generation
│   ├── generators/
│   │   ├── prediction-pdf.ts       # Prediction report PDF
│   │   └── treatment-pdf.ts        # Treatment report PDF
│   ├── index.ts
│   └── templates.ts                # PDF templates/styles
│
└── reports/                        # Reports management
    ├── components/                 # Report-specific components
    │   ├── report-card.tsx
    │   ├── report-detail.tsx
    │   ├── report-filters.tsx
    │   ├── report-list.tsx
    │   ├── report-skeleton.tsx
    │   └── index.ts
    ├── hooks.ts                    # Report hooks
    ├── index.ts                    # Barrel export
    ├── service.ts                  # Firestore CRUD operations
    └── types.ts                    # Report type definitions

---

Config Directory (/src/config)

config/
├── index.ts                        # Barrel export
├── constants.ts                    # Application constants
└── parameters.ts                   # Water quality parameters config

---

Key File Responsibilities

File	Responsibility
app/layout.tsx	Root layout, AuthProvider wrapper
app/(core)/layout.tsx	Protected routes layout with sidebar
lib/auth-context.tsx	Authentication state management
lib/firebase.ts	Firebase app initialization
lib/ml-api/client.ts	ML API communication
lib/blockchain/service.ts	Blockchain operations
lib/reports/service.ts	Firestore report CRUD
config/parameters.ts	Water quality parameter definitions

---

Naming Conventions

Files

• Pages: page.tsx (Next.js convention)
• Components: kebab-case.tsx
• Hooks: use-[name].ts
• Services: service.ts or [name]-service.ts
• Types: types.ts
• Utils: utils.ts or descriptive name

Exports

• Barrel exports: index.ts in each module folder
• Named exports: Preferred over default exports
• Component exports: Match filename

---

Last Updated: December 2024