Skip to content

README.md

Latest commit

 

History

History
201 lines (161 loc) · 11.9 KB

README.md

File metadata and controls

201 lines (161 loc) · 11.9 KB

oneCard - Digital Cards Store Platform

MERN Stack Next.js Docker Scalable

oneCard is a high-performance digital cards marketplace built with modern web technologies. This platform enables users to create, buy, and manage digital business cards with a focus on scalability, maintainability, and developer experience.

🌟 Key Features

  • MVC Architecture - Clean separation of concerns in backend
  • Next.js 14 - App Router, Server Components, and ISR
  • Scalable Infrastructure - Docker Compose ready for production
  • Responsive Design - Mobile-first UI with Tailwind CSS

📂 Project Structure

Backend (MVC Architecture)

backend/
├── config/             # Environment configs & DB connection
├── controllers/        # Business logic (MVC Controllers)
├── models/             # Data schemas (MVC Models)
├── routes/             # API endpoints (MVC Routes)
├── services/           # Reusable business logic (for scaling)
├── utils/              # Helpers, middleware, error handlers
├── validations/        # Request validation schemas
└── server.js           # Entry point

Frontend (Next.js 14 App Router)

frontend/
├── app/                # Next.js App Router structure
│   ├── (auth)/         # Authentication routes
│   ├── api/            # Server-side API routes
│   ├── cards/          # Card management routes
│   ├── dashboard/      # User dashboard
│   ├── layout.tsx      # Root layout
│   └── page.tsx        # Home page
├── components/         # Reusable UI components
├── lib/                # Shared logic (API clients, utils)
├── public/             # Static assets
├── styles/             # Global styles
└── next.config.js      # Next.js configuration

🚀 Getting Started

Prerequisites

  • Node.js v18+
  • MongoDB (local or cloud instance)
  • Docker (optional for containerized setup)

Installation

1. Clone the repository

git clone https://github.com/aliBenhenia/OneCard-Morocco
cd OneCard-Morocco

2. Install dependencies

Frontend (Next.js):

cd frontend
npm install -f  # Force install to handle potential peer dependency issues
npm run dev

Backend (Express):

cd ../backend
npm install
npm install -g nodemon  # Global installation for development
nodemon src/server.js

Frontend runs at: http://localhost:3000
Backend API runs at: http://localhost:3001

4. Alternative: Docker Compose Setup

docker-compose up --build

This will:

  • Build and run frontend container (port 3000)
  • Build and run backend container (port 3001)

🔬 Architecture Deep Dive

MVC Pattern Implementation

graph LR
    A[Client Request] --> B[Routes]
    B --> C[Controllers]
    C --> D[Services]
    D --> E[Models]
    E --> F[MongoDB]
    F --> E
    E --> D
    D --> C
    C --> B
    B --> A
Loading
  1. Routes: Define API endpoints (/api/cards, /api/users)
  2. Controllers: Handle request/response logic
  3. Services: Reusable business logic (decoupled from HTTP)
  4. Models: Data schemas and database operations

Why This Structure Scales

  • Service Layer: Critical for microservices transition later
  • Validation Separation: Dedicated validation layer prevents controller bloat
  • Middleware Pipeline: Custom middleware for auth, logging, errors
  • Next.js App Router: Built-in caching, data fetching, and route handlers

Composed Infrastructure Design

graph TB
    A[Client] --> B[Nginx Load Balancer]
    B --> C[Frontend Cluster]
    B --> D[Backend Cluster]
    D --> E[Redis Cache]
    D --> F[MongoDB Cluster]
    D --> G[Payment Service]
    D --> H[Notification Service]
Loading

For future scaling:

  1. Frontend: CDN + Static Export (Next.js)
  2. Backend: Kubernetes pods with auto-scaling
  3. Database: MongoDB Atlas sharding
  4. Caching: Redis for session and query caching
  5. Async Processing: RabbitMQ for background jobs

📈 Scaling Strategy

Phase 1: Monolith (Current)

  • Single Express server
  • Next.js frontend
  • MongoDB replica set

Phase 2: Service Decomposition

  1. Extract User Service
  2. Create Card Processing Service
  3. Implement Notification Service
  4. Separate Payment Gateway

Phase 3: Cloud-Native Deployment

  • Frontend: Vercel/Netlify (SSG)
  • Backend: AWS ECS/Fargate
  • Database: MongoDB Atlas
  • Infrastructure: Terraform-managed

🛠 Development Workflow

Frontend Commands

npm run dev       # Start dev server
npm run build     # Create production build
npm run lint      # Run linter

Backend Commands

npm start         # Production start
npm run dev       # Dev mode with nodemon
npm test          # Run tests

Docker Commands

docker-compose up      # Start full stack
docker-compose down    # Stop containers
docker-compose logs -f # Follow logs

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📜 License

Distributed under MIT License. See LICENSE for more information.

Pro Tip: For production deployment, always use docker-compose -f docker-compose.prod.yml up -d with production-optimized configuration. The development setup includes hot-reloading and debugging tools not suitable for production.

oneCard - Where digital connections begin ✨