Skip to main content

FeelyFeely Marketplace Documentation

Welcome to the comprehensive documentation for the FeelyFeely Marketplace application - a full-stack React-based marketplace platform.

Table of Contents​

  1. Overview
  2. Project Structure
  3. Getting Started
  4. Technology Stack
  5. Architecture
  6. Development Guide
  7. Deployment
  8. API Reference
  9. Contributing

Overview​

FeelyFeely is a marketplace application that allows users to:

  • Browse and search marketplace items
  • Manage homes, places, and events
  • Create and manage business listings
  • User authentication and profile management
  • Real-time chat functionality
  • Location-based services with maps
  • Payment processing with Paystack

Project Structure​

ff-ui/
├── src/
│   ├── client/                 # Frontend React application
│   │   ├── components/         # Reusable UI components
│   │   ├── pages/             # Page components
│   │   ├── stores/            # Zustand state management
│   │   ├── types/             # TypeScript type definitions
│   │   ├── assets/            # Static assets (images, icons)
│   │   ├── hooks/             # Custom React hooks
│   │   ├── lib/               # Utility libraries
│   │   ├── utils/             # Helper functions
│   │   ├── App.tsx            # Main App component
│   │   ├── main.tsx           # Application entry point
│   │   └── index.css          # Global styles
│   └── server/                # Backend Express server
├── public/                    # Public static files
├── dist/                      # Build output
├── scripts/                   # Build scripts
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── vite.config.js             # Vite build configuration
├── tailwind.config.cjs        # Tailwind CSS configuration
└── README.md                  # Project readme

Getting Started​

Prerequisites​

  • Node.js (version 18 or higher)
  • npm or yarn package manager
  • MongoDB database
  • Git

Installation​

  1. Clone the repository:

    git clone https://github.com/FeelyFeely/ff-web-ui.git
    cd ff-web-ui

  2. Install dependencies:

    yarn install
    # or
    npm install

  3. Environment Setup: Create a .env file in the root directory with the following variables:

    NODE_ENV=development
    MONGODB_URI=your_mongodb_connection_string
    SESSION_SECRET=your_session_secret
    PAYSTACK_PUBLIC_KEY=your_paystack_public_key
    PAYSTACK_SECRET_KEY=your_paystack_secret_key
    GOOGLE_MAPS_API_KEY=your_google_maps_api_key
    ANTHROPIC_API_KEY=your_anthropic_api_key

  4. Start the development server:

    yarn dev
    # This starts both the client and server in development mode

  5. Open your browser: Navigate to http://localhost:3000 to view the application.

Available Scripts​

  • yarn dev - Start development server with hot reloading
  • yarn build - Build the application for production
  • yarn preview - Preview the built application
  • yarn start - Start the production server

Technology Stack​

Frontend​

  • React 19 - UI library with latest features
  • TypeScript - Type-safe JavaScript
  • Vite - Fast build tool and development server
  • Tailwind CSS - Utility-first CSS framework
  • Framer Motion - Animation library
  • React Router - Client-side routing
  • Zustand - Lightweight state management
  • React Query - Server state management
  • React Hook Form - Form handling
  • Leaflet - Interactive maps
  • Socket.io Client - Real-time communication

Backend​

  • Express.js - Web framework for Node.js
  • MongoDB - NoSQL database
  • Session Management - Express sessions with MongoDB store
  • Socket.io - Real-time communication
  • Multer - File upload handling
  • CORS - Cross-origin resource sharing

Development Tools​

  • ESLint - Code linting
  • TypeScript - Static type checking
  • Nodemon - Development server auto-restart
  • Concurrently - Run multiple commands
  • TSC-Alias - TypeScript path mapping

External Services​

  • Paystack - Payment processing
  • Google Maps - Location services
  • Anthropic Claude - AI chat functionality
  • Plausible - Privacy-focused analytics

Architecture​

Client Architecture​

The client follows a component-based architecture with the following key patterns:

1. Pages Structure​

pages/
├── Main/              # Landing page
├── Market/            # Marketplace pages
├── Homes/             # Home listings
├── Places/            # Places and locations
├── Events/            # Event listings
├── Business/          # Business management
├── User/              # User profile and account
├── Collection/        # User collections
└── EarthMapper/       # Map visualization

2. State Management​

  • Zustand stores for client-side state
  • React Query for server state and caching
  • Local storage for persistence

3. Routing​

React Router 7 with:

  • Nested routes for organized page structure
  • Protected routes for authenticated users
  • Lazy loading for performance optimization

Server Architecture​

The server follows an Express.js pattern with:

  • Route handlers for API endpoints
  • Middleware for authentication, logging, and CORS
  • Session management with MongoDB store
  • Socket.io for real-time features

Development Guide​

Code Organization​

Component Guidelines​

  • Use functional components with hooks
  • Follow TypeScript naming conventions
  • Implement proper prop interfaces
  • Use composition over inheritance

State Management​

  • Use Zustand for client state
  • Use React Query for server state
  • Keep state as local as possible
  • Use derived state when appropriate

Styling Guidelines​

  • Use Tailwind CSS utility classes
  • Create reusable component variants
  • Follow responsive design principles
  • Use CSS variables for theming

TypeScript Best Practices​

  • Define strict interfaces for props
  • Use union types for variants
  • Implement proper error boundaries
  • Use generic types when appropriate

Key Features Implementation​

1. Marketplace Functionality​

The marketplace supports multiple categories:

  • Products (Market)
  • Homes and real estate
  • Places and venues
  • Events

Each category has:

  • Listing pages with filtering
  • Detail pages with full information
  • Category-specific search
  • User reviews and ratings

2. User Authentication​

  • Session-based authentication
  • User profiles and preferences
  • Organization accounts
  • Role-based permissions

3. Real-time Features​

  • Live chat functionality
  • Real-time notifications
  • Socket.io integration
  • Presence indicators

4. Payment Integration​

  • Paystack payment processing
  • Secure transaction handling
  • Payment status tracking
  • Multiple payment methods

5. Location Services​

  • Google Maps integration
  • Leaflet maps for property visualization
  • Location-based search
  • Interactive map features

Testing Strategy​

Unit Testing​

  • Component testing with React Testing Library
  • Hook testing for custom hooks
  • Utility function testing
  • Type checking with TypeScript

Integration Testing​

  • API endpoint testing
  • Database integration testing
  • Payment flow testing
  • Authentication testing

Performance Testing​

  • Bundle size optimization
  • Loading performance
  • Memory usage monitoring
  • Network request optimization

Deployment​

Production Build​

  1. Build the application:

    yarn build

  2. Environment Configuration: Set production environment variables:

    NODE_ENV=production
    MONGODB_URI=production_mongodb_uri
    # Other production variables

  3. Start production server:

    yarn start

Docker Deployment​

  1. Create Dockerfile:

    FROM node:18-alpine
    WORKDIR /app
    COPY package*.json ./
    RUN npm ci --only=production
    COPY . .
    RUN npm run build
    EXPOSE 3000
    CMD ["npm", "start"]

  2. Build and run:

    docker build -t feelyfeely-app .
    docker run -p 3000:3000 feelyfeely-app

Environment Variables​

Production environment requires:

  • Database connection strings
  • API keys for external services
  • Session secrets
  • Payment gateway credentials
  • Analytics tracking codes

API Reference​

Authentication Endpoints​

  • POST /api/auth/login - User login
  • POST /api/auth/logout - User logout
  • POST /api/auth/register - User registration
  • GET /api/auth/profile - Get user profile

Marketplace Endpoints​

  • GET /api/market - Get marketplace items
  • POST /api/market - Create new listing
  • GET /api/market/:id - Get specific item
  • PUT /api/market/:id - Update listing
  • DELETE /api/market/:id - Delete listing

Search and Filtering​

  • GET /api/search - Global search
  • GET /api/filter - Apply filters
  • GET /api/categories - Get categories

Real-time Events​

  • connection - User connects
  • message - Chat messages
  • notification - System notifications
  • disconnect - User disconnects

Contributing​

Getting Started with Development​

  1. Fork the repository
  2. Create a feature branch: 
    git checkout -b feature/your-feature-name
  3. Make your changes
  4. Write tests for new functionality
  5. Run the test suite: 
    yarn test
  6. Submit a pull request

Code Standards​

  • Follow TypeScript strict mode
  • Use ESLint configuration
  • Write meaningful commit messages
  • Include tests for new features
  • Update documentation as needed

Pull Request Guidelines​

  • Provide clear description of changes
  • Include screenshots for UI changes
  • Ensure all tests pass
  • Update relevant documentation
  • Request appropriate reviewers

Additional Resources​

For questions or support, please refer to the project's GitHub issues or contact the development team.