ReparaYa - Local Services Marketplace

ReparaYa is a responsive web marketplace that connects clients with verified local service contractors (plumbing, electricity, carpentry, etc.) in the Guadalajara Metropolitan Area.

Project Structure

ProyectoFinal/
├── backend/                 # Node.js + Express backend
│   ├── src/
│   │   ├── controllers/    # HTTP request handlers
│   │   ├── services/       # Business logic layer
│   │   ├── repositories/   # Data access layer
│   │   ├── middleware/     # Express middleware
│   │   ├── routes/         # API route definitions
│   │   ├── validators/     # Request validation schemas
│   │   ├── utils/          # Utility functions
│   │   └── config/         # Configuration files
│   ├── prisma/             # Database schema and migrations
│   └── tests/              # Backend tests
│       ├── unit/           # Unit tests
│       ├── integration/    # Integration tests
│       └── e2e/            # End-to-end tests
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/    # Reusable React components
│   │   ├── pages/         # Page-level components
│   │   ├── context/       # React Context providers
│   │   ├── hooks/         # Custom React hooks
│   │   ├── services/      # API client services
│   │   └── utils/         # Utility functions
│   └── public/            # Static assets
├── infrastructure/         # Infrastructure as Code
│   └── terraform/         # Terraform configurations
│       ├── modules/       # Reusable Terraform modules
│       └── environments/  # Environment-specific configs
├── scripts/               # Automation scripts
│   ├── aws_scaling.sh    # AWS scaling setup
│   └── aws_teardown.sh   # AWS resource cleanup
├── openspec/             # Project specifications
│   ├── project.md        # Project conventions
│   ├── specs/            # Current specifications
│   ├── changes/          # Proposed changes
│   └── openspec_tasks.md # Development tasks breakdown
└── docs/                 # Additional documentation

Tech Stack

Backend

• Runtime: Node.js
• Framework: Express
• Database: PostgreSQL with Prisma ORM
• Cache: Redis
• Authentication: JWT with bcrypt

Frontend

• Framework: React
• Styling: Tailwind CSS
• State Management: Context API / Zustand
• Routing: React Router

Cloud & Infrastructure

• Provider: AWS
• Services: S3, SES, Location Service, CloudWatch, ALB, ASG
• IaC: Terraform
• Payments: Stripe (Checkout + Connect Express)

Testing

• Backend: Jest + Supertest
• Frontend: React Testing Library + Jest
• E2E: Cypress / Playwright
• Performance: k6 / JMeter

Quick Start

Prerequisites

• Node.js >= 18
• PostgreSQL >= 14
• Redis >= 6
• AWS CLI configured
• Stripe account

Setup

1. Clone and install dependencies:

   # Install backend dependencies
   cd backend
   npm install
   
   # Install frontend dependencies
   cd ../frontend
   npm install

2. Configure environment:

   # Copy example env file
   cp .env.example .env
   
   # Edit .env with your actual credentials

3. Set up database:

   cd backend
   npx prisma migrate dev
   npx prisma db seed

4. Run development servers:

   # Terminal 1 - Backend
   cd backend
   npm run dev
   
   # Terminal 2 - Frontend
   cd frontend
   npm run dev

Development Workflow

OpenSpec Workflow

This project uses OpenSpec for spec-driven development. See openspec/AGENTS.md for detailed instructions.

Git Workflow

• Main branch: main (always deployable)
• Feature branches: feat/FR-XXX-description or fix/bug-description
• Pull Requests: Required for all merges, must pass CI checks

Code Conventions

• Naming: camelCase for variables/functions, PascalCase for components/classes
• Linting: ESLint + Prettier
• Testing: >= 70% code coverage required

Architecture

Backend Architecture

• Pattern: 3-tier monolithic (Controllers -> Services -> Repositories)
• Stateless: Designed for horizontal scaling
• Observability: X-Request-ID tracing, structured JSON logging

Messaging System (Hot/Cold Storage)

• Hot Storage (Redis): Last 10-20 messages for fast loading
• Cold Storage (PostgreSQL): Full message history with pagination

Pricing Model

• B: Base price set by contractor
• recargo: 0-20% markup for out-of-coverage services
• B': Adjusted base (B × (1 + recargo))
• P: Public price (B' × 1.15) - 15% platform markup
• anticipo: 20% advance payment
• liquidación: 80% completion payment

Performance Requirements (NFRs)

• Search (FR-005): P95 latency <= 1.2s
• Service Detail (FR-007): P95 latency <= 1.0s
• Availability: >= 99.5% monthly uptime

AWS Cost Control

Use the provided scripts to manage AWS resources:

# Provision base scaling infrastructure
./scripts/aws_scaling.sh

# Tear down all AWS resources (DESTRUCTIVE - staging only!)
./scripts/aws_teardown.sh

Testing

# Backend unit tests
cd backend
npm test

# Backend integration tests
npm run test:integration

# Frontend tests
cd frontend
npm test

# E2E tests
npm run test:e2e

# Coverage report
npm run test:coverage

Deployment

See infrastructure/terraform/README.md for deployment instructions.

Documentation

• Project Specifications
• Development Tasks
• OpenSpec Agent Guide
• API Documentation - Coming soon
• Database Schema - Coming soon

Security

• OWASP Top 10 mitigations implemented
• No PAN/CVV storage (Stripe handles all payment data)
• LFPDPPP compliance for privacy (ARCO rights)
• WCAG 2.1 AA accessibility standards

Support

For issues or questions, please refer to the project documentation or contact the development team.

License

Proprietary - All rights reserved