superyacht-tech-docs.md

Superyacht Technology Platform - Technical Documentation

Table of Contents

1. Technology Stack Overview
2. Database Design
   • MongoDB Schema Models
3. API Endpoints
   • Authentication
   • Users & Teams
   • Technologies
   • Companies & Suppliers
   • Projects
   • Recommendations
   • Videos & Pitches
4. Frontend Components
   • Layout Components
   • Authentication Components
   • Dashboard Components
   • Technology Database Components
   • Companies & Suppliers Components
   • Projects Components
   • Video & Pitch Components
   • Shared Components
5. Development Timeline

Technology Stack Overview

Frontend

• Framework: Vite React with TypeScript
• Styling: Tailwind CSS 4.0
• State Management: React Context API with useReducer hooks
• Routing: React Router
• HTTP Client: Axios
• Hosting: Render.com

Backend

• API Framework: Express.js
• Database: MongoDB with Mongoose ODM
• Authentication: Custom JWT implementation
• File Storage: Cloudinary for videos and images
• Search: MongoDB Atlas Search
• Hosting: Render.com

DevOps

• Version Control: Git
• CI/CD: GitHub Actions with automatic deployment to Render.com

Database Design

MongoDB Schema Models

User Schema

const UserSchema = new mongoose.Schema({
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
  firstName: { type: String, required: true },
  lastName: { type: String, required: true },
  role: { 
    type: String, 
    enum: ['engineer', 'avit_officer', 'eto', 'project_manager', 'supplier', 'admin'], 
    required: true 
  },
  company: { type: mongoose.Schema.Types.ObjectId, ref: 'Company' },
  profileImage: { type: String },
  specializations: [{ type: String }],
  projects: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Project' }],
  savedTechnologies: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Technology' }],
  lastLogin: { type: Date },
  refreshTokens: [{ token: String, expires: Date }],
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

// Pre-save middleware to hash password
UserSchema.pre('save', async function(next) {
  if (this.isModified('password')) {
    this.password = await bcrypt.hash(this.password, 10);
  }
  next();
});

// Method to compare password for login
UserSchema.methods.comparePassword = async function(candidatePassword) {
  return bcrypt.compare(candidatePassword, this.password);
};

// Method to generate JWT token
UserSchema.methods.generateAuthToken = function() {
  return jwt.sign(
    { id: this._id, email: this.email, role: this.role },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );
};

// Method to generate refresh token
UserSchema.methods.generateRefreshToken = function() {
  const refreshToken = crypto.randomBytes(40).toString('hex');
  const expires = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
  
  this.refreshTokens.push({ token: refreshToken, expires });
  return { refreshToken, expires };
};

Company Schema

const CompanySchema = new mongoose.Schema({
  name: { type: String, required: true, unique: true },
  logo: { type: String },
  website: { type: String },
  description: { type: String, required: true },
  type: { 
    type: String, 
    enum: ['supplier', 'shipyard', 'management', 'service_provider', 'other'],
    required: true 
  },
  contactEmail: { type: String, required: true },
  contactPhone: { type: String },
  address: {
    street: { type: String },
    city: { type: String },
    state: { type: String },
    country: { type: String, required: true },
    postalCode: { type: String }
  },
  technologies: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Technology' }],
  pitchVideos: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Video' }],
  employees: [{ type: mongoose.Schema.Types.ObjectId, ref: 'User' }],
  yearFounded: { type: Number },
  socialMedia: {
    linkedin: { type: String },
    twitter: { type: String },
    facebook: { type: String },
    instagram: { type: String }
  },
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

Technology Schema

const TechnologySchema = new mongoose.Schema({
  name: { type: String, required: true },
  supplier: { type: mongoose.Schema.Types.ObjectId, ref: 'Company', required: true },
  category: { 
    type: String, 
    enum: [
      'navigation', 'communication', 'entertainment', 'security', 
      'propulsion', 'electrical', 'automation', 'lighting',
      'hvac', 'water_management', 'av_systems', 'it_infrastructure', 'other'
    ],
    required: true 
  },
  subcategory: { type: String },
  description: { type: String, required: true },
  technicalSpecs: { type: mongoose.Schema.Types.Mixed },
  installationRequirements: { type: String },
  certifications: [{ type: String }],
  images: [{ type: String }],
  manuals: [{ type: String }],
  datasheets: [{ type: String }],
  videos: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Video' }],
  pricing: {
    estimate: { type: String },
    priceRange: {
      min: { type: Number },
      max: { type: Number }
    },
    currency: { type: String, default: 'USD' }
  },
  compatibilities: [{ type: String }],
  releaseDate: { type: Date },
  tags: [{ type: String }],
  ratings: [{
    user: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
    score: { type: Number, min: 1, max: 5 },
    comment: { type: String },
    date: { type: Date, default: Date.now }
  }],
  averageRating: { type: Number, default: 0 },
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

Project Schema

const ProjectSchema = new mongoose.Schema({
  name: { type: String, required: true },
  codeName: { type: String, unique: true },
  description: { type: String },
  client: { type: String },
  manager: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  team: [{ type: mongoose.Schema.Types.ObjectId, ref: 'User' }],
  shipyard: { type: mongoose.Schema.Types.ObjectId, ref: 'Company' },
  yachtDetails: {
    length: { type: Number },
    beam: { type: Number },
    draft: { type: Number },
    displacement: { type: Number },
    buildMaterial: { type: String },
    type: { type: String, enum: ['motor', 'sail', 'power', 'other'] }
  },
  selectedTechnologies: [{
    technology: { type: mongoose.Schema.Types.ObjectId, ref: 'Technology' },
    assignedBy: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
    assignedAt: { type: Date, default: Date.now },
    status: { 
      type: String, 
      enum: ['proposed', 'approved', 'rejected', 'installed', 'pending'],
      default: 'proposed' 
    },
    notes: { type: String }
  }],
  budget: {
    total: { type: Number },
    spent: { type: Number },
    currency: { type: String, default: 'USD' }
  },
  timeline: {
    startDate: { type: Date },
    expectedDelivery: { type: Date },
    milestones: [{
      name: { type: String },
      date: { type: Date },
      completed: { type: Boolean, default: false }
    }]
  },
  status: { 
    type: String, 
    enum: ['planning', 'in_progress', 'on_hold', 'completed', 'cancelled'],
    default: 'planning' 
  },
  documents: [{
    name: { type: String },
    file: { type: String },
    uploadedBy: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
    uploadDate: { type: Date, default: Date.now }
  }],
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

Video Schema

const VideoSchema = new mongoose.Schema({
  title: { type: String, required: true },
  description: { type: String },
  url: { type: String, required: true },
  thumbnailUrl: { type: String },
  type: { 
    type: String, 
    enum: ['pitch', 'demonstration', 'installation', 'tutorial', 'other'],
    required: true 
  },
  duration: { type: Number }, // in seconds
  uploadedBy: { 
    user: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
    company: { type: mongoose.Schema.Types.ObjectId, ref: 'Company' }
  },
  relatedTechnology: { type: mongoose.Schema.Types.ObjectId, ref: 'Technology' },
  tags: [{ type: String }],
  views: { type: Number, default: 0 },
  likes: { type: Number, default: 0 },
  uploadDate: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
});

API Endpoints

Authentication Endpoints

POST /api/auth/register

• Description: Register a new user
• Request Body:
  • email: string
  • password: string
  • firstName: string
  • lastName: string
  • role: string (engineer, avit_officer, eto, project_manager, supplier, admin)
  • company: ObjectId (optional)
• Response: User object with JWT token
• Implementation: Custom JWT generation stored in MongoDB

POST /api/auth/login

• Description: Authenticate a user
• Request Body:
  • email: string
  • password: string
• Response: User object with JWT token and refresh token
• Implementation: Custom JWT validation against MongoDB user record

POST /api/auth/refresh

• Description: Refresh JWT token
• Request Body:
  • refreshToken: string
• Response: New JWT token
• Implementation: Validates refresh token against MongoDB records

POST /api/auth/logout

• Description: Invalidate refresh token
• Request Body:
  • refreshToken: string
• Response: Success message
• Implementation: Removes refresh token from user's refreshTokens array

Users & Teams Endpoints

GET /api/users/me

• Description: Get current user profile
• Response: User object
• Security: Requires valid JWT

PUT /api/users/me

• Description: Update current user profile
• Request Body: User data to update
• Response: Updated user object
• Security: Requires valid JWT

GET /api/users/:id

• Description: Get user by ID
• Response: User object
• Security: Requires valid JWT with appropriate role

GET /api/teams

• Description: Get all teams user belongs to
• Response: Array of team objects
• Security: Requires valid JWT

POST /api/teams

• Description: Create a new team
• Request Body: Team data
• Response: Created team object
• Security: Requires valid JWT with appropriate role

GET /api/teams/:id

• Description: Get team by ID
• Response: Team object
• Security: Requires valid JWT and team membership

PUT /api/teams/:id

• Description: Update team
• Request Body: Team data to update
• Response: Updated team object
• Security: Requires valid JWT and team admin role

DELETE /api/teams/:id

• Description: Delete team
• Response: Success message
• Security: Requires valid JWT and team admin role

Technologies Endpoints

GET /api/technologies

• Description: Get all technologies
• Query Parameters:
  • category: string
  • supplier: ObjectId
  • search: string
  • page: number
  • limit: number
  • sort: string
• Response: Array of technology objects with pagination metadata
• Security: Requires valid JWT

GET /api/technologies/:id

• Description: Get technology by ID
• Response: Technology object
• Security: Requires valid JWT

POST /api/technologies

• Description: Create a new technology (admin/supplier only)
• Request Body: Technology data
• Response: Created technology object
• Security: Requires valid JWT with admin or supplier role

PUT /api/technologies/:id

• Description: Update technology (admin/supplier only)
• Request Body: Technology data to update
• Response: Updated technology object
• Security: Requires valid JWT with admin or appropriate supplier role

DELETE /api/technologies/:id

• Description: Delete technology (admin only)
• Response: Success message
• Security: Requires valid JWT with admin role

POST /api/technologies/:id/rate

• Description: Rate a technology
• Request Body:
  • score: number (1-5)
  • comment: string (optional)
• Response: Updated technology object with new rating
• Security: Requires valid JWT

GET /api/technologies/compare

• Description: Compare multiple technologies
• Query Parameters:
  • ids: Array of technology IDs
• Response: Comparison data
• Security: Requires valid JWT

Companies & Suppliers Endpoints

GET /api/companies

• Description: Get all companies
• Query Parameters:
  • type: string
  • search: string
  • page: number
  • limit: number
• Response: Array of company objects with pagination metadata
• Security: Requires valid JWT

GET /api/companies/:id

• Description: Get company by ID
• Response: Company object
• Security: Requires valid JWT

POST /api/companies

• Description: Create a new company (admin only)
• Request Body: Company data
• Response: Created company object
• Security: Requires valid JWT with admin role

PUT /api/companies/:id

• Description: Update company (admin/company owner only)
• Request Body: Company data to update
• Response: Updated company object
• Security: Requires valid JWT with admin or company owner role

DELETE /api/companies/:id

• Description: Delete company (admin only)
• Response: Success message
• Security: Requires valid JWT with admin role

GET /api/companies/:id/technologies

• Description: Get all technologies from a specific company
• Response: Array of technology objects
• Security: Requires valid JWT

GET /api/companies/:id/videos

• Description: Get all videos from a specific company
• Response: Array of video objects
• Security: Requires valid JWT

Projects Endpoints

GET /api/projects

• Description: Get all projects user has access to
• Query Parameters:
  • status: string
  • search: string
  • page: number
  • limit: number
• Response: Array of project objects with pagination metadata
• Security: Requires valid JWT

GET /api/projects/:id

• Description: Get project by ID
• Response: Project object
• Security: Requires valid JWT and project access

POST /api/projects

• Description: Create a new project
• Request Body: Project data
• Response: Created project object
• Security: Requires valid JWT with project manager role

PUT /api/projects/:id

• Description: Update project
• Request Body: Project data to update
• Response: Updated project object
• Security: Requires valid JWT and project manager role

DELETE /api/projects/:id

• Description: Delete project
• Response: Success message
• Security: Requires valid JWT and project manager role

POST /api/projects/:id/technologies

• Description: Add technology to project
• Request Body:
  • technologyId: ObjectId
  • status: string (proposed, approved, rejected, installed, pending)
  • notes: string (optional)
• Response: Updated project object
• Security: Requires valid JWT and project access

PUT /api/projects/:id/technologies/:techId

• Description: Update technology status in project
• Request Body:
  • status: string
  • notes: string (optional)
• Response: Updated project object
• Security: Requires valid JWT and project access

DELETE /api/projects/:id/technologies/:techId

• Description: Remove technology from project
• Response: Updated project object
• Security: Requires valid JWT and project manager role

POST /api/projects/:id/documents

• Description: Upload document to project
• Request Body: FormData with file
• Response: Updated project object
• Security: Requires valid JWT and project access

Recommendations Endpoints

GET /api/recommendations/technologies

• Description: Get technology recommendations based on user profile and history
• Query Parameters:
  • category: string (optional)
  • limit: number (optional, default: 10)
• Response: Array of recommended technology objects
• Security: Requires valid JWT

GET /api/recommendations/similar/:techId

• Description: Get similar technologies to a specific technology
• Query Parameters:
  • limit: number (optional, default: 5)
• Response: Array of similar technology objects
• Security: Requires valid JWT

GET /api/recommendations/project/:projectId

• Description: Get technology recommendations for a specific project
• Query Parameters:
  • category: string (optional)
  • limit: number (optional, default: 10)
• Response: Array of recommended technology objects
• Security: Requires valid JWT and project access

Videos & Pitches Endpoints

GET /api/videos

• Description: Get all videos
• Query Parameters:
  • type: string
  • company: ObjectId
  • technology: ObjectId
  • search: string
  • page: number
  • limit: number
• Response: Array of video objects with pagination metadata
• Security: Requires valid JWT

GET /api/videos/:id

• Description: Get video by ID
• Response: Video object
• Security: Requires valid JWT

POST /api/videos

• Description: Upload a new video
• Request Body: FormData with video file and metadata
• Response: Created video object
• Security: Requires valid JWT with appropriate role

PUT /api/videos/:id

• Description: Update video metadata
• Request Body: Video data to update
• Response: Updated video object
• Security: Requires valid JWT and video ownership

DELETE /api/videos/:id

• Description: Delete video
• Response: Success message
• Security: Requires valid JWT and video ownership or admin role

POST /api/videos/:id/view

• Description: Increment video view count
• Response: Updated video object
• Security: Requires valid JWT

POST /api/videos/:id/like

• Description: Like/unlike video
• Response: Updated video object
• Security: Requires valid JWT

Frontend Components

Layout Components

<AppLayout>

• Main layout wrapper with navigation
• Children: Sidebar, Header, Main Content Area, Footer

<Sidebar>

• Navigation sidebar with links to main sections
• Job-role specific navigation options

<Header>

• Top navigation bar with user profile, notifications, search

<Footer>

• Site footer with links and copyright information

<DashboardLayout>

• Layout specific for dashboard views
• Children: DashboardSidebar, DashboardContent

Authentication Components

<LoginForm>

• User login form
• Email/password inputs with validation
• Uses Context API for auth state management

<RegisterForm>

• New user registration form
• Personal details, role selection, company association
• Uses Context API for auth state management

<ForgotPasswordForm>

• Password recovery form

<ResetPasswordForm>

• Form to set new password after recovery

<RoleSelector>

• Component for selecting user role during registration

Dashboard Components

<DashboardHome>

• Main dashboard view
• Shows recent activities, saved technologies, active projects

<UserProfile>

• Profile management component
• Edit personal details, change password, manage preferences

<NotificationsPanel>

• Display and manage user notifications

<ActivityFeed>

• Timeline of recent activities and updates

<QuickActions>

• Buttons for common actions based on user role

Technology Database Components

<TechnologyBrowser>

• Main component for browsing technology database
• Includes filters, search, and results display

<TechnologyFilters>

• Filter options for technology search
• By category, supplier, ratings, etc.

<TechnologyCard>

• Card display for individual technology
• Shows key information, image, rating

<TechnologyDetail>

• Detailed view of selected technology
• Full specifications, documentation, videos

<TechnologyCompare>

• Side-by-side comparison of multiple technologies

<TechnologyRating>

• Component for rating and reviewing technologies

<TechnicalSpecsTable>

• Tabular display of technical specifications

Companies & Suppliers Components

<CompanyBrowser>

• Browse and search company/supplier listings

<CompanyCard>

• Card display for company information

<CompanyProfile>

• Detailed company profile page
• Shows information, technologies, videos

<SupplierDirectory>

• Directory listing of suppliers by category

<CompanyContactForm>

• Form to contact company representatives

Projects Components

<ProjectDashboard>

• Overview of active projects

<ProjectDetail>

• Detailed view of specific project
• Shows team, technologies, timeline, budget

<ProjectCreator>

• Form to create new project

<TechnologyAssignment>

• Component for assigning technologies to projects

<ProjectTimeline>

• Visual timeline of project milestones

<TeamMembers>

• Display and manage project team members

<BudgetTracker>

• Track project budget allocation and spending

Video & Pitch Components

<VideoGallery>

• Browse and search video content

<VideoPlayer>

• Custom video player component

<VideoUploader>

• Component for uploading and processing videos

<VideoCard>

• Card display for video preview

<DockwalkPitchSection>

• Section specifically for browsing Dockwalk pitches

Shared Components

<SearchBar>

• Global search component

<Pagination>

• Component for paginated results

<SortSelector>

• Dropdown for sorting options

<FilterPanel>

• Reusable filter panel for various listings

<LoadingSpinner>

• Loading indicator component

<ErrorBoundary>

• Error handling wrapper component

<ConfirmationModal>

• Modal for confirming actions

<NotificationToast>

• Toast notification component

<ImageGallery>

• Component for displaying multiple images

<DropdownMenu>

• Reusable dropdown menu component

<Breadcrumbs>

• Navigation breadcrumbs component

<Tabs>

• Tabbed interface component

<FileUploader>

• Component for uploading files

<TagSelector>

• Component for managing tags

Development Timeline

Phase 1: Setup & Infrastructure

• Project setup, Git repository initialization
• Development environment configuration
• Database schema design and implementation
• API routes planning and basic implementation
• JWT authentication system setup
• Frontend scaffolding with Vite and React Router
• Setup Render.com projects for both frontend and backend

Phase 2: Core Functionality

• Database models implementation
• REST API development for all core endpoints
• User authentication with JWT and refresh tokens
• Basic CRUD operations for all resources
• File upload system for documents and videos with Cloudinary
• Frontend skeleton with routing
• Context API setup for global state management
• Setup CI/CD pipeline with GitHub Actions for Render.com deployment

Phase 3: Frontend Development

• Component development based on component list
• Implement pages for all main sections
• Connect frontend to API endpoints
• Styling with Tailwind CSS 4.0
• Responsive design implementation
• Form validation and error handling
• Auth context implementation for secure routes

Phase 4: Advanced Features

• AI recommendation engine implementation
• Video processing and thumbnail generation via Cloudinary
• Project management features
• Technology comparison functionality
• Advanced search and filtering
• User dashboard personalization
• Role-based access control implementation

Phase 5: Testing & Optimization

• Unit and integration testing
• Performance optimization
• Security audit and implementation
• Cross-browser testing
• Accessibility improvements
• Documentation completion
• Render.com staging environment testing

Phase 6: Deployment & Launch

• Production environment setup on Render.com
• Database migration
• CI/CD pipeline finalization
• Final testing in production environment
• User acceptance testing
• Marketing website and launch preparation
• Monitoring and analytics setup