Finalize the Isaac Alves code test

[isaaclvs]

User Management System

A full-featured user management application built with Ruby on Rails 7.1.6, featuring admin dashboard, user import functionality, and real-time progress tracking.

🚀 Features

Admin Features

• Admin Dashboard with user statistics and counters
• User Management: Create, read, update, and delete users
• Role Management: Toggle user roles (admin/user)
• Spreadsheet Import: Import users from CSV/Excel files with real-time progress tracking
• User Statistics: View total users and users grouped by role

User Features

• Profile Management: View and edit own profile
• Avatar Upload: Upload avatar images via file or URL
• Account Deletion: Delete own account

Visitor Features

• User Registration: Self-registration as regular user

🛠️ Tech Stack

• Ruby: 3.3.4
• Rails: 7.1.6
• Database: PostgreSQL 16
• Frontend: Bootstrap 5.3.8, Stimulus, Turbo
• Authentication: Devise 4.9
• Authorization: Pundit
• Background Jobs: ActiveJob
• File Processing: Roo (CSV/Excel)
• Testing: RSpec, FactoryBot, SimpleCov
• Code Quality: Rubocop

📋 Prerequisites

• Ruby 3.3.4 (use rbenv or asdf)
• PostgreSQL 16 (with development libraries: libpq-dev on Debian/Ubuntu, postgresql-dev on Alpine)
• Node.js 22.21.0
• Yarn 1.22.22
• Docker and Docker Compose (optional, for containerized setup)

Note: The pg gem will be installed automatically via bundle install. Make sure PostgreSQL development libraries are installed on your system.

🔧 Installation

Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd user_test

2. Run setup script (recommended)

   bin/setup

   This will automatically:

   • Install Ruby dependencies
   • Install JavaScript dependencies
   • Prepare the database
   • Clear logs and temp files

3. Or set up manually

   # Install Ruby dependencies
   bundle install
   
   # Install JavaScript dependencies
   yarn install
   
   # Set up the database
   rails db:create db:migrate db:seed

4. Start the development server

   # Using Procfile.dev (recommended - runs web, js, and css watchers)
   bin/dev
   
   # Or manually
   rails server
   # In separate terminals:
   yarn build --watch    # JavaScript watcher
   yarn watch:css        # CSS watcher

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

Docker Setup

1. Build and start containers

   docker-compose up --build

2. Set up the database (first time only)

   docker-compose exec app rails db:create db:migrate db:seed

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

🧪 Testing

Run all tests

rspec

Run specific test files

# Model tests
rspec spec/models

# Controller tests
rspec spec/controllers

# Request tests
rspec spec/requests

# Job tests
rspec spec/jobs

Test coverage

The project uses SimpleCov for test coverage reporting. After running tests, view the coverage report:

# macOS
open coverage/index.html

# Linux
xdg-open coverage/index.html

# Or open manually
# File location: coverage/index.html

The project aims for 90%+ test coverage. Coverage reports include:

• Models
• Controllers
• Jobs
• Policies
• Services

📝 Database

Default Credentials (Development)

• Admin: admin@example.com / password123
• User: user@example.com / password123

Database Configuration

The application uses PostgreSQL. Configuration is in config/database.yml:

• Development: user_test_development
• Test: user_test_test
• Production: user_test_production

Database Tasks

# Create database
rails db:create

# Run migrations
rails db:migrate

# Rollback last migration
rails db:rollback

# Seed database
rails db:seed

# Reset database (drop, create, migrate, seed)
rails db:reset

📤 User Import

CSV/Excel Format

The import feature supports CSV and Excel (.xls, .xlsx) files with the following format:

Column	Description	Required	Default
Full Name	User's full name	Yes	-
Email	User's email address	Yes	-
Password	User password	No	Random generated
Role	user or admin	No	user
Avatar URL	URL to avatar image	No	-

Example CSV

Full Name,Email,Password,Role,Avatar URL
John Doe,john.doe@example.com,password123,user,https://example.com/avatar.jpg
Jane Smith,jane.smith@example.com,password456,admin,
Bob Johnson,bob.johnson@example.com,,user,https://example.com/avatar2.jpg

Import Process

1. Navigate to Admin > Users
2. Click Import Users button
3. Select CSV or Excel file
4. Monitor progress in real-time (if ActionCable is enabled)
5. View import status and results

🏗️ Project Structure

user_test/
├── app/
│   ├── controllers/        # Application controllers
│   │   ├── admin/         # Admin namespace controllers
│   │   └── ...
│   ├── models/            # ActiveRecord models
│   ├── views/             # ERB templates
│   ├── jobs/              # Background jobs
│   ├── policies/          # Pundit authorization policies
│   └── javascript/        # Stimulus controllers
├── config/                # Application configuration
├── db/                    # Database migrations and seeds
├── spec/                  # RSpec tests
├── Dockerfile             # Docker image definition
└── docker-compose.yml     # Docker Compose configuration

🔐 Authentication & Authorization

Authentication

• Uses Devise for user authentication
• Supports registration, login, logout, password recovery

Authorization

• Uses Pundit for authorization policies
• Admin users can:
  • Access admin dashboard
  • Manage all users (CRUD)
  • Import users
  • Toggle user roles
• Regular users can:
  • View and edit own profile
  • Delete own account

🎨 Frontend

CSS Framework

• Bootstrap 5.3.8 for responsive design
• Bootstrap Icons for icons
• SCSS for stylesheet compilation

JavaScript

• Stimulus for interactive components
• Turbo for SPA-like navigation
• Bootstrap JavaScript for UI components

🔄 Background Jobs

The application uses ActiveJob for asynchronous processing:

• UserImportJob: Processes user imports from spreadsheets
• ImportUsersJob: Alternative import job with progress tracking

Jobs are processed using the default queue adapter (async in development, configurable in production).

📊 Code Quality

Linters

The project uses Rubocop for code quality:

# Check code style
bundle exec rubocop

# Auto-fix issues
bundle exec rubocop -a

Test Coverage

Test coverage is tracked with SimpleCov. View reports in coverage/index.html after running tests.

🐳 Docker

Docker Compose Services

• app: Rails application
• db: PostgreSQL database

Docker Commands

# Start services
docker-compose up

# Start in background
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f app

# Execute commands in container
docker-compose exec app rails console
docker-compose exec app rspec

🌐 Browser Support

The application is tested and supports:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

🔧 Configuration

Environment Variables

Create a .env file in the root directory for local development:

# Database (if not using docker-compose)
DB_HOST=localhost
DB_USERNAME=postgres
DB_PASSWORD=postgres

# Rails
RAILS_ENV=development
SECRET_KEY_BASE=your_secret_key_base

ActionCable (Realtime)

ActionCable is configured but currently commented out in config/application.rb. To enable:

1. Uncomment require "action_cable/engine" in config/application.rb
2. Configure ActionCable adapter in config/cable.yml
3. Set up WebSocket server (Redis recommended for production)

🚢 Deployment

Production Considerations

• Set RAILS_ENV=production
• Configure SECRET_KEY_BASE
• Set up PostgreSQL database
• Configure ActionCable adapter (Redis recommended)
• Set up background job processor (Sidekiq, Resque, etc.)
• Configure Active Storage for file uploads
• Set up reverse proxy (Nginx, Apache)
• Enable SSL/TLS

Docker Production Build

docker build -t user-test:latest .
docker run -p 3000:3000 \
  -e RAILS_ENV=production \
  -e DATABASE_URL=postgres://user:pass@host:5432/dbname \
  -e SECRET_KEY_BASE=your_secret_key_base \
  user-test:latest

📚 API Documentation

Routes

Admin Routes (requires admin role)

• GET /admin/dashboard - Admin dashboard
• GET /admin/users - List all users
• POST /admin/users - Create user
• GET /admin/users/:id - Show user
• PATCH /admin/users/:id - Update user
• DELETE /admin/users/:id - Delete user
• PATCH /admin/users/:id/toggle_role - Toggle user role
• POST /admin/users/import - Import users from file
• GET /admin/imports/new - New import form
• POST /admin/imports - Create import
• GET /admin/imports/:id - Show import status

User Routes (authenticated)

• GET /profile - Show own profile
• GET /profile/edit - Edit profile form
• PATCH /profile - Update profile
• DELETE /profile - Delete own account

Public Routes

• GET / - Home page
• GET /users/sign_in - Login
• POST /users/sign_in - Login
• GET /users/sign_up - Registration
• POST /users/sign_up - Registration

🐛 Troubleshooting

Database Connection Issues

# Check PostgreSQL is running
sudo service postgresql status

# Check database exists
rails db:version

# Reset database
rails db:reset

Asset Compilation Issues

# Rebuild assets
yarn build
yarn build:css

# Clear asset cache
rails assets:clobber
rails assets:precompile

Test Failures

# Reset test database
rails db:test:prepare

# Run tests with verbose output
rspec --format documentation

📄 License

This project is part of a technical assessment.

👥 Author

Developed as part of a Fullstack Developer technical test.

---

Note: This application was built following best practices including:

• RESTful API design
• Proper HTTP methods (GET, POST, PATCH, DELETE)
• Security considerations (XSS, CSRF protection)
• Responsive design
• Test coverage (90%+)
• Code quality (Rubocop)
• Docker support
• Real-time features (ActionCable ready)