Local Development Setup

This guide provides comprehensive instructions for setting up your local development environment to work on the Tank Safe IMS (Inspection Management System) portal. The Tank Safe IMS is a comprehensive digital inspection management system designed specifically for road tanker safety inspections and compliance reporting.

Prerequisites

Before you begin, ensure your development environment meets these requirements:

System Requirements

Tool	Version	Notes
Node.js	18.x LTS or later	Current: 22.x recommended. Required for both portal and docs.
npm	9.x or later	Comes bundled with Node.js.
Git	2.30+	Required for version control and repository operations.
Supabase Account	Latest	Required for backend services and authentication.

Recommended Development Tools

Tool	Purpose	Installation
Visual Studio Code	Primary IDE	Download
GitHub Desktop	Git GUI (optional)	Download
Postman	API testing	Download

VS Code Extensions

Install these recommended extensions for optimal development experience:

{
  "recommendations": [
    "ms-vscode.vscode-typescript-next",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-json",
    "christian-kohler.path-intellisense",
    "ms-vscode-remote.remote-containers"
  ]
}

Project Overview

The Tank Safe IMS is organized as a monorepo with the following key components:

• Main Application: React + TypeScript application built with Vite
• Documentation Site: Docusaurus-based documentation
• Supabase Backend: Database, authentication, and edge functions
• UI Components: shadcn/ui component library with Tailwind CSS

Technology Stack

• Frontend: React 18, TypeScript, Vite
• Styling: Tailwind CSS, shadcn/ui components
• Backend: Supabase (PostgreSQL, Auth, Edge Functions)
• State Management: TanStack Query, React Hook Form
• Charts: Recharts
• PDF Generation: React PDF Renderer
• Canvas/Drawing: Konva.js, Fabric.js

Installation & Setup

1. Clone the Repository

git clone https://github.com/TheITCloudGuy/tank-wise-portal.git
cd tank-wise-portal

2. Install Dependencies

# Install dependencies for the main application
npm install

# Install dependencies for the documentation site
cd docusaurus/tanksafe-docs
npm install
cd ../..

3. Verify Installation

# Check Node.js and npm versions
node --version  # Should be 18.x or later
npm --version   # Should be 9.x or later

# Verify project structure
ls -la

Environment Configuration

Supabase Setup

The application requires a Supabase project for backend services. You have two options:

Option A: Use Existing Supabase Project

1. Create a new project at supabase.com
2. Note your project URL and API keys from the project settings

Option B: Use Local Supabase (Advanced)

For advanced development, you can run Supabase locally using Docker:

# Install Supabase CLI
npm install -g supabase

# Start local Supabase instance
supabase start

Environment Variables

Create environment configuration files:

Main Application (.env.local)

# Create in the repository root
touch .env.local

Add the following variables:

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key-here

# Optional: Development features
VITE_DEMO_MODE=false

Security Note

Never commit .env* files to version control. They contain sensitive API keys and should remain local to your development environment.

Documentation Site (.env)

# Create in docusaurus/tanksafe-docs/
cd docusaurus/tanksafe-docs
touch .env

# Firebase Configuration (for docs features)
FIREBASE_API_KEY=your-firebase-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-project.appspot.com
FIREBASE_APP_ID=your-app-id
FIREBASE_MEASUREMENT_ID=your-measurement-id

# Supabase (if docs need backend features)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

Running the Application

Development Servers

Main Application (Tank Safe IMS Portal)

# From repository root
npm run dev

• URL: http://localhost:8080
• Framework: Vite + React + TypeScript
• Features: Hot reload, fast refresh, development mode

Documentation Site

# From repository root
cd docusaurus/tanksafe-docs
npm run start

• URL: http://localhost:3000
• Framework: Docusaurus
• Features: Hot reload, live preview

Running Both Simultaneously

Use multiple terminal sessions or a process manager like concurrently:

# Install concurrently globally (optional)
npm install -g concurrently

# Run both servers
concurrently "npm run dev" "cd docusaurus/tanksafe-docs && npm run start"

First Time Setup

After starting the development server:

1. Access the Application: Open http://localhost:8080
2. Create Admin Account: Use Supabase dashboard to create your first admin user
3. Configure Authentication: Set up authentication providers in Supabase
4. Test Core Features: Try creating a sample inspection to verify setup

Development Workflow

Code Quality Tools

Linting

# Lint the main application
npm run lint

# Fix auto-fixable linting issues
npm run lint -- --fix

Type Checking

# TypeScript type checking
npx tsc --noEmit

Building for Production

Main Application

# Development build
npm run build:dev

# Production build
npm run build

# Preview production build locally
npm run preview

Documentation Site

cd docusaurus/tanksafe-docs

# Build for production
npm run build

# Serve production build locally
npm run serve

Available Scripts

Script	Description
npm run dev	Start the Vite dev server on port 8080
npm run build	Build the application for production
npm run build:dev	Build in development mode
npm run lint	Run ESLint code linting
npm run preview	Preview the production build locally
npm run check-form-data	Validate form data structure

Project Structure

tank-wise-portal/
├── src/                          # Main application source code
│   ├── components/               # React components (UI, forms, etc.)
│   ├── hooks/                    # Custom React hooks
│   ├── lib/                      # Utility libraries and helpers
│   ├── pages/                    # Application pages/routes
│   ├── types/                    # TypeScript type definitions
│   └── integrations/             # External service integrations
├── supabase/                     # Supabase configuration and functions
│   ├── config.toml              # Supabase project configuration
│   ├── functions/               # Edge functions (admin operations)
│   └── migrations/              # Database schema migrations
├── docusaurus/                   # Documentation site
│   └── tanksafe-docs/           # Docusaurus project
├── public/                       # Static assets (images, icons)
├── dist/                         # Build output (generated)
├── package.json                  # Project dependencies and scripts
├── vite.config.ts               # Vite configuration
├── tailwind.config.ts           # Tailwind CSS configuration
├── tsconfig.json                 # TypeScript configuration
└── eslint.config.js              # ESLint configuration

Database & Backend

Supabase Configuration

Local Development

# Initialize Supabase in your project
supabase init

# Link to your remote project
supabase link --project-ref your-project-id

# Pull remote schema
supabase db pull

Database Migrations

# Create new migration
supabase migration new your_migration_name

# Apply migrations
supabase db push

# Reset database
supabase db reset

Edge Functions

Edge functions handle admin operations and are deployed separately:

# Deploy functions
supabase functions deploy

# View function logs
supabase functions logs

# Serve functions locally
supabase functions serve

Key Features & Workflows

Inspection Management

The core functionality revolves around managing tanker inspections:

• Risk Assessment: Initial safety evaluation and work authorization
• Multiple Inspection Types: Vapour tightness, leakproofness, EPRV testing, etc.
• Digital Forms: Structured data collection with validation
• Signature Capture: Digital signature collection for certifications
• PDF Generation: Automated report generation

User Management

• Role-Based Access: Admin, Inspector, and Client roles
• Multi-Factor Authentication: Enhanced security for admin accounts
• User Invitations: Email-based user onboarding

Dashboard & Analytics

• Real-Time Statistics: Active inspections and completion metrics
• Performance Tracking: Monthly completion rates and efficiency reporting
• Job Management: Complete visibility into inspection status

Testing

Manual Testing Checklist

After setup, verify these core functionalities:

• Application loads without errors
• User authentication (sign up/sign in)
• Admin dashboard access
• Create new inspection
• Form data validation
• PDF generation
• Responsive design (mobile/desktop)
• Cross-browser compatibility

Development Testing

# Run form data validation
npm run check-form-data

# Check for TypeScript errors
npx tsc --noEmit

# Lint code
npm run lint

Future Testing

Automated test suites (Vitest, Playwright) are planned for future development releases.

Deployment

Production Deployment

The application supports multiple deployment platforms:

Vercel (Recommended)

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel

# Production URL will be provided after deployment

Netlify

# Build commands are configured in build settings
npm run build

Environment Variables for Production

Ensure these environment variables are set in your deployment platform:

VITE_SUPABASE_URL=your-production-supabase-url
VITE_SUPABASE_PUBLISHABLE_KEY=your-production-anon-key
VITE_DEMO_MODE=false

Troubleshooting

Common Issues

Build Errors

Issue: Module not found errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Issue: TypeScript compilation errors

# Check TypeScript configuration
npx tsc --showConfig

# Run type checking
npx tsc --noEmit

Runtime Errors

Issue: Supabase connection failures

• Verify .env.local contains correct credentials
• Check Supabase project status and API keys
• Ensure CORS is configured for your domain

Issue: Authentication issues

• Clear browser storage/cookies
• Verify MFA configuration in Supabase
• Check user permissions and roles

Issue: Port conflicts

# Kill process on port 8080
npx kill-port 8080

# Or use different port
npm run dev -- --port 8081

Development Server Issues

Issue: Hot reload not working

• Check file watching limits: cat /proc/sys/fs/inotify/max_user_watches
• Increase if necessary: echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches

Performance Issues

Issue: Slow development server

• Clear Vite cache: rm -rf node_modules/.vite
• Check for large dependencies
• Consider using npm run build:dev for faster builds

Getting Help

1. Check Existing Issues: Search GitHub Issues
2. Documentation: Review this guide and related technical documentation
3. Community: Check project discussions or create new issue
4. Logs: Enable verbose logging for debugging

Contributing

Development Guidelines

• Follow the existing code style and TypeScript conventions
• Use ESLint configuration for code quality
• Add JSDoc comments for complex functions and components
• Maintain consistent naming conventions
• Test changes across different browsers and devices

Git Workflow

1. Create Feature Branch

   git checkout -b feature/your-feature-name

2. Make Changes

   • Follow conventional commit messages
   • Run linting and type checking before committing

3. Commit Changes

   git add .
   git commit -m "feat: add new inspection workflow"

4. Push and Create PR

   git push origin feature/your-feature-name

Code Review Process

• Ensure all tests pass (when available)
• Verify responsive design
• Check accessibility compliance
• Validate against design system
• Test on multiple browsers

Next Steps

After completing this setup:

1. Explore the Application: Familiarize yourself with the inspection workflows
2. Review the Codebase: Understand the component architecture and data flow
3. Test Core Features: Create sample inspections and verify functionality
4. Check Documentation: Review the docs site for API references and guides
5. Start Contributing: Begin working on assigned issues or new features

For additional help, refer to:

• Component Architecture
• Contributing Guide
• User Guides