oneCard - Digital Cards Store Platform

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 ✨