SimpleShare

SimpleShare is a modern web application that allows users to upload and share files easily. This project provides a simple and intuitive interface for file sharing with a clean, Vue.js 3 frontend and robust Node.js/TypeScript backend.

Features

• User-friendly interface built with Vue.js 3 and Composition API
• File upload functionality with progress tracking and drag-and-drop support
• User authentication and registration system with secure session management
• Dashboard for managing uploaded files with intuitive UI
• Responsive design with Tailwind CSS and custom animations
• Admin panel for comprehensive user management
• File sharing via unique codes for secure access
• Group file uploads with batch operations
• Real-time notifications and user feedback
• Quota management system for storage control
• Mobile-responsive design optimized for all devices
• Database migration system for easy schema updates
• Modern confirmation modal system replacing browser alerts
• Update screen for maintenance mode during server updates
• TypeScript support throughout the codebase for better maintainability

Technology Stack

• Frontend: Vue.js 3 (Composition API), Vue Router, Tailwind CSS, Vite
• Backend: Node.js, Express.js, TypeScript
• Database: MariaDB with automated migration system
• Authentication: bcrypt for password hashing, secure session tokens
• File Handling: Multer for multipart uploads, Archiver for zip operations
• Development Tools: Concurrently, Nodemon, Prettier, TypeScript compiler
• Styling: Tailwind CSS v4 with custom animations and responsive design

Project Structure

simpleShare/
├── backend/                 # Backend API server (TypeScript)
│   ├── src/
│   │   ├── adminActions.ts  # Admin operations and user management
│   │   ├── auth.ts          # Authentication and session logic
│   │   ├── routes.ts        # API route definitions
│   │   ├── server.ts        # Express server setup
│   │   ├── uploadActions.ts # File upload and management
│   │   ├── userActions.ts   # User operations
│   │   ├── db.ts            # Database connection
│   │   ├── migration-runner.ts # Database migration system
│   │   └── controllers/     # API controllers
│   ├── migrations/          # Database migration files
│   └── tsconfig.json        # TypeScript configuration
├── client/                  # Frontend Vue.js application
│   ├── public/              # Static assets
│   ├── src/
│   │   ├── components/      # Reusable Vue components
│   │   │   ├── UpdateScreen.vue    # Maintenance/update screen
│   │   │   ├── Notification.vue    # Notification system
│   │   │   └── ConfirmModal.vue    # Confirmation modal
│   │   ├── composables/     # Vue composables (useConfirm, useUpdateStatus, etc.)
│   │   ├── views/           # Page views and routing
│   │   ├── App.vue          # Root component with global modals
│   │   └── main.js          # Application entry point
│   ├── index.html           # HTML template
│   ├── tailwind.config.js   # Tailwind configuration
│   └── vite.config.js       # Vite build configuration
├── uploads/                 # File storage directory
├── dist/                    # Compiled TypeScript output
├── .env.example             # Environment variables template
├── .gitignore              # Git ignore rules
├── MIGRATIONS.md           # Database migration documentation
├── Alert-box.md            # Confirmation modal system documentation
├── LICENSE                 # MIT License
├── README.md               # This file
└── package.json            # Dependencies and npm scripts

Installation

Method 1. - Manual Install (Recommended)

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• MariaDB database server

Setup Steps

1. Clone the repository:

   git clone https://github.com/cigoria/simpleShare.git
   cd simpleShare

2. Install the dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env

   Edit .env for your setup:

   DATABASE_URL="mysql://username:password@localhost:3306/mydb"
   DATABASE_USER="username"
   DATABASE_PASSWORD="password"
   DATABASE_NAME="mydb"
   DATABASE_HOST="localhost"
   DATABASE_PORT=3306
   
   PORT=3000
   UPLOAD_PATH=./uploads/
   
   DEFAULT_ADMIN_USERNAME=admin
   DEFAULT_ADMIN_PASSWORD=admin
   DEFAULT_ADMIN_QUOTA=10737418240
   

4. Database Setup:

   Create an empty database named simpleShare in MariaDB. The migration system will automatically create all necessary tables when you start the server.

5. Build the application:

   npm run build

6. Start the production server:

   npm start

   The application will be available at http://localhost:3000

Method 2. - Docker (Beta)

Images availible for use:

• ghcr.io/cigoria/simpleshare:latest
• registry.gitlab.com/cigoria/simpleshare:latest

1. docker-compose.yaml

---
services:
  db:
    image: mariadb:latest
    container_name: simpleShare_db
    restart: unless-stopped
    environment:
      MYSQL_USER: ${DBUSER}
      MYSQL_PASSWORD: ${DBPASS}
      MYSQL_DATABASE: ${DB}
      MYSQL_ROOT_PASSWORD: ${DBRPASS}
    volumes:
      - ${DBDATA}:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 10

  simpleShare:
    image: registry.gitlab.com/cigoria/simpleshare:latest
    # image: ghcr.io/cigoria/simpleshare:latest
    container_name: simpleShare
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: mysql://${DBUSER}:${DBPASS}@${DBHOST}:${DBPORT}/${DB}
      DATABASE_USER: ${DBUSER}
      DATABASE_PASSWORD: ${DBPASS}
      DATABASE_NAME: ${DB}
      DATABASE_HOST: ${DBHOST}
      DATABASE_PORT: ${DBPORT}
      PORT: ${PORT}
      UPLOAD_PATH: ${UPLOAD}
      DEFAULT_ADMIN_USERNAME: ${DEFUSER}
      DEFAULT_ADMIN_PASSWORD: ${PASS}
      DEFAULT_ADMIN_QUOTA: ${QUOTA}
    ports:
      - 3000:3000

2. Folder structure

mkdir DB
touch .env

3. Edit .env for your setup:

DB=simpleshare
DBDATA=/Docker/simpleShare/DB/
DBHOST=db
DBPORT=3306
DBRPASS=simpleshare
DBUSER=simpleshare
DBPASS=simpleshare
PASS=admin
PORT=3000
QUOTA=10737418240
UPLOAD=./uploads/
DEFUSER=admin

4. Start container

docker compose up -d

5. Open browser at: http://localhost:3000

Development

Development Mode with Hot Reload

For development with hot reload on both frontend and backend:

npm run dev

This command uses concurrently to run both frontend and backend development servers simultaneously.

Individual Development Servers

If you prefer to run servers separately:

1. Start the backend server with auto-reload:

   npm run dev:backend

2. In another terminal, start the frontend dev server:

   npm run dev:frontend

Development URLs

• Frontend: http://localhost:5173 (Vite dev server)
• Backend API: http://localhost:3000 (Express server)

Available Scripts

• npm run dev - Run both frontend and backend in development mode
• npm run dev:backend - Run only backend with TypeScript compilation and auto-reload
• npm run dev:frontend - Run only frontend with Vite hot reload
• npm run build - Build both frontend and backend for production
• npm run build:backend - Compile TypeScript backend to dist/
• npm run build:frontend - Build Vue.js frontend for production
• npm start - Start production server from compiled files
• npm run clean - Remove compiled dist/ directory
• npm run update:start - Show maintenance screen during updates
• npm run update:stop - Hide maintenance screen after updates

Code Quality

The codebase follows these quality standards:

• TypeScript: Full type safety in backend, progressive adoption in frontend
• Code Style: Prettier configuration for consistent formatting
• Vue.js Best Practices: Composition API, proper component structure
• Documentation: Inline comments for complex logic, comprehensive README
• Error Handling: Modern confirmation modals instead of browser alerts

API Endpoints

Authentication

• POST /login - User login with email/password
• POST /register - User registration with validation
• GET /logout - User logout and session cleanup
• GET /verifySession - Verify active session token

File Operations

• POST /upload - Upload single file with metadata
• POST /upload-group - Upload multiple files as a group
• GET /files/:code - Download file by unique code
• GET /checkFile - Check if file exists by code
• GET /delete/:code - Delete file by code (owner/admin only)
• GET /getAllFiles - Get all files for current user
• GET /quota - Get user quota and usage information

Admin Operations

• GET /admin/users - List all users (admin only)
• POST /admin/user/:id/ban - Ban/unban user (admin only)
• POST /admin/user/:id/quota - Update user quota (admin only)
• Additional endpoints for user management and system administration

Update Status Management

• GET /api/update-status - Get current update status
• POST /api/update-status - Set update status (maintenance mode)

Key Systems

Database Migration System

The project uses an automated migration system for database schema management:

• Migration files: Located in /backend/migrations/ with numeric prefixes
• Automatic execution: Migrations run automatically on server startup
• Version tracking: Applied migrations are tracked in the migrations table
• Safe rollback: Failed migrations are automatically rolled back

For detailed information, see MIGRATIONS.md.

Confirmation Modal System

Modern confirmation dialogs replace browser alerts throughout the application:

• Reusable components: ConfirmModal.vue with useConfirm composable
• Multiple types: Info, warning, error, success dialogs
• Customizable: Custom buttons, icons, and messages
• Accessible: Keyboard navigation and proper focus management
• Animated: Smooth transitions and backdrop effects

For usage examples and documentation, see Alert-box.md.

Update Screen System

The application includes a maintenance screen that appears during server updates:

• Automatic display: Shows when server is in update mode
• Real-time polling: Frontend checks update status every 5 seconds
• Clean UI: Modern loading animation with informative messages
• Easy control: Simple npm scripts to toggle maintenance mode

Usage:

# Show maintenance screen
npm run update:start

# Hide maintenance screen
npm run update:stop

Components:

• UpdateScreen.vue - Maintenance screen component
• useUpdateStatus.js - Composable for status polling
• updateStatus.ts - Backend controller for status management

Authentication & Security

• Secure password hashing using bcrypt
• Session-based authentication with secure tokens
• Role-based access control for admin features
• File access control via unique codes and ownership verification

Contributing

We welcome contributions from the community! Here's how to get started:

Development Workflow

1. Fork the repository on GitHub
2. Create a feature branch from the main branch:

   git checkout -b feature/your-feature-name

3. Make your changes following our code standards
4. Test your changes thoroughly:
   • Run npm run dev to test in development mode
   • Test both frontend and backend functionality
   • Ensure database migrations work if you've modified the schema
5. Format your code using Prettier:

   npm run format

6. Commit your changes with clear, descriptive messages
7. Push to your fork and create a pull request

Code Standards

• TypeScript: Use proper types in backend, consider types in frontend
• Vue.js: Use Composition API, follow component best practices
• CSS: Use Tailwind CSS classes, avoid inline styles
• Comments: Write clear comments in English for complex logic
• Confirmation dialogs: Use the useConfirm composable instead of browser alerts
• Database changes: Create migration files for any schema modifications

Areas for Contribution

• Frontend: UI improvements, new components, accessibility enhancements
• Backend: API optimizations, new features, security improvements
• Documentation: Better documentation, examples, guides
• Testing: Unit tests, integration tests, end-to-end tests
• Performance: Optimization, caching, database improvements

Pull Request Guidelines

• Provide a clear description of changes
• Reference any related issues
• Include screenshots for UI changes
• Ensure all tests pass
• Keep PRs focused on a single feature or fix

Getting Help

Documentation

• MIGRATIONS.md - Database migration system documentation
• Alert-box.md - Confirmation modal system guide
• API Endpoints - Listed above with descriptions
• Project Structure - Detailed directory overview

Troubleshooting

Common Issues:

1. Database Connection Errors

   • Ensure MariaDB is running
   • Check .env configuration matches database credentials
   • Verify the database simpleShare exists

2. Migration Failures

   • Check database permissions
   • Ensure migration files have correct naming format
   • Review migration SQL for syntax errors

3. Build Errors

   • Run npm install to update dependencies
   • Clear dist/ directory with npm run clean
   • Check Node.js version compatibility (v16+)

4. File Upload Issues

   • Ensure uploads/ directory exists and is writable
   • Check file size limits in configuration
   • Verify disk space availability

Support

For questions, bug reports, or feature requests:

• Create an issue on GitHub
• Check existing issues for solutions
• Review documentation before asking questions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Contributors: Thanks to all developers who have contributed to this project
• Technologies: Built with modern web technologies for optimal performance
• Community: Special thanks to our users for feedback and suggestions

Project Creators

• zeti1223 - Frontend development and UI/UX design
• FonixPython - Backend development