DAD Project - Bisca Game Platform

Overview

The DAD project aims to develop and deploy the Bisca Game Platform as a web application. The platform is a distributed system that provides users with the ability to play the traditional Portuguese card game Bisca in single-player and multiplayer modes, manage their coins, and track their gaming statistics.

The web client is implemented as a Single-Page Application (SPA) built with Vue.js and hosted on the designated internal school server. The backend system includes a database, a RESTful API server, and a WebSocket server for real-time multiplayer gameplay.

Project Architecture

Frontend

• Technology: Vue.js SPA
• Purpose: User interface for game play, user management, coin transactions, and statistics visualization
• Features: Real-time game updates via WebSockets, responsive design, player profiles, leaderboards

Backend

• RESTful API Server: Handles user authentication, coin transactions, game history, leaderboards, and administrative operations
• WebSocket Server: Manages real-time multiplayer game communication, ensuring the server acts as the authoritative source for game state
• Database: Persists user data, game results, transactions, and platform statistics

Constraints

The project must adhere to the following mandatory constraints:

1. Single-Page Application (SPA) - The application must be implemented exclusively as an SPA
2. Vue.js Requirement - The client application must be built with Vue.js
3. Payment Gateway Integration - All external coin purchases must be processed via the provided RESTful API (Payment Gateway Service)
4. Deployment - The application must be deployed on the designated internal school server and be accessible via a desktop web browser
5. Backend Technologies - Must be open-source or available as free external services
6. Server Compatibility - Backend technologies must be installable on or accessible from the designated server; if not supported, compliant alternatives must be selected
7. Database Seeding - The deployed application's database must be seeded with realistic data in both scale and content to simulate typical usage patterns

Core Features

1. User Management

• Registration: Users register with email, nickname, name, password (minimum 3 characters), and optional photo/avatar
• Authentication: Email and password-based login
• Profile Management: View and update profile information, change password
• Sign Out: Users can end their session
• Account Deletion: Requires explicit confirmation; permanently forfeits all coins
• Welcome Bonus: New users receive 10 coins upon registration
• Admin Accounts: Created only by existing administrators; same profile capabilities as users but cannot delete their own accounts

2. Coins and Transactions

• Coin Balance: Users can view their current coin balance
• Coin Purchases: External purchases via Payment Gateway Service
• Conversion Rate: €1 = 10 coins (purchases in €1 increments)
• Coin Earning: Players earn coins through gameplay and bonuses
• Transaction History: All coin-related transactions (bonuses, purchases, spending, earnings) are logged
• History Access:
  • Players view only their own transaction history
  • Administrators have read-only access to all players' histories
  • Administrators cannot create, modify, or delete transactions

3. Games and Matches

Game Variants

• Bisca de 3: Three-card hands
• Bisca de 9: Nine-card hands

Game Modes

• Single-Player: Against a bot (available to anonymous and registered users)
• Multiplayer: Against human opponents (available only to registered users)
• Match: Best-of series (up to 4 marks/wins) with two players

Game Rules

• Games and matches are limited to two players
• The bot follows game rules and attempts to win when playing second; otherwise plays its lowest-value card
• Official Bisca rules apply (as defined in the "Bisca Game" documentation)

Multiplayer Gameplay

• Real-Time Communication: WebSockets for live game updates
• Server Authority: The server is the source of truth for:
  • Card dealing
  • Turn order
  • Valid moves
  • Trick resolution
  • Drawing from stock
  • Scoring
  • End-of-game/match conditions
• Move Timer: 20-second limit per move
• Resignation:
  • Opponent awarded all remaining cards
  • Game ends immediately
  • If in a match, player forfeits all remaining games
  • Scores computed accordingly
• Persistent Results: Game and match results with metadata are persisted for user history and administrative access

4. Game History and Leaderboards

Tracking

• Scope: Only multiplayer games and matches are tracked
• Metadata: Start/end timestamps, variant, outcome (win/loss/draw/forfeit), final points, marks (capote, bandeira), duration

History Access

• Players: View only their own multiplayer history
• Administrators: Read-only access to all players' histories and detailed records
• Detailed Records: Visible only to administrators and participating players

Leaderboards

• Personal Leaderboards: Visible only to the owner; summarize totals for game wins, match wins, capotes, and bandeiras (optionally segmented by variant)
• Global Leaderboards: Visible to all users including anonymous visitors; highlight top players by game and match wins, may include capotes and bandeiras
• Tie-Breaking: Earlier achievers rank higher in case of ties

5. Administration

Administrator Capabilities

• Profile Management: Same as regular users, except cannot delete their own accounts
• Account Management: Create new administrator accounts, remove any account except their own
• Soft Deletion: Player accounts with prior activity must be soft-deleted
• User Monitoring: View all users (players and administrators), block/unblock players
• Read-Only Access:
  • All transactions
  • All multiplayer games and matches
  • Platform usage summaries and statistics

Administrator Access Control

• Cannot play games or hold coins
• New administrator accounts can only be created by existing administrators

6. Statistics and Reporting

Anonymous Users and Players

• Access only generic, anonymized aggregates:
  • Total registered players
  • Games and matches played
  • Recent activity summaries

Administrators

• Full, non-anonymized access including:
  • Purchases by period and player
  • Game/match volumes
  • User activity breakdowns
  • Time-series data

Visualization

• Statistics available in both visual (charts) and textual/tabular forms
• Privacy for non-admin viewers is preserved
• Exact metrics and visualizations are team-defined

Enhancement and Innovation Opportunities

To distinguish this project, consider implementing one or more of the following:

Custom Features (Examples)

• Support for three or more players per game (optional extension while preserving two-player mode)
• Spectator mode for multiplayer games and matches
• Full playback of past games
• Custom card sets
• Extended bot capabilities (e.g., improved AI strategies)
• Integration of bots into multiplayer games

Architecture and Performance Enhancements (Examples)

• Queue server or worker for asynchronous, long-running operations
• Horizontal scaling of the WebSocket server
• Session recovery after WebSocket or node failures
• Cache server implementation
• NoSQL database for specific use cases
• Search engine for game history or statistics
• Asynchronous messaging broker (e.g., Kafka, RabbitMQ)
• Distributed components for improved scalability and resilience

Implementation Quality

• Use of technologies or techniques not covered in standard coursework
• Performance optimization with empirical benchmarks
• Improved architecture and code structure
• Enhanced implementation quality and documentation

Note: Credit is proportional to demonstrated impact with preference given to distributed capabilities that improve architecture, scalability, or resilience.

Technology Stack

Frontend

• Vue.js (mandatory)
• Vite (build tool)
• ESLint (code quality)

Backend

• API Server: Open-source, student-selected technology
• WebSocket Server: Open-source, student-selected technology
• Database: Open-source, student-selected technology
• All must be compatible with the designated school server

Supported Variants

• Laravel (PHP) for REST API
• Node.js for WebSocket server

Project Structure

DADProject/
├── api/                    # Laravel REST API backend
├── frontend/               # Vue.js SPA
├── websockets/            # WebSocket server
└── README.md              # This file

Getting Started

Refer to the individual README.md files in each directory for setup and deployment instructions:

• API Documentation
• Frontend Documentation
• WebSocket Server Documentation

Database Schema

The application's database includes the following primary entities:

• Users: Player and administrator accounts
• Games: Individual game records (both single-player and multiplayer)
• Matches: Match records (series of games)
• Coin Transactions: Purchase and spending history
• Coin Transaction Types: Transaction categorization
• Coin Purchases: External purchase records
• Leaderboard Data: Aggregated player statistics

For detailed schema information, refer to the database migrations in the api/database/migrations/ directory.

Key Business Rules

1. Coin System:

   • New users receive 10 welcome coins
   • Conversion rate: €1 = 10 coins
   • Coin purchases are made in €1 increments
   • All transactions are logged and immutable (except soft-deleted accounts)

2. Game Rules:

   • Two-player games only (in standard mode)
   • Bot cannot be played in multiplayer
   • 20-second move timer in multiplayer
   • Resignation forfeits remaining games in a match

3. Account Management:

   • Administrators cannot be created via public registration
   • Administrators cannot delete their own accounts
   • Account deletion requires explicit confirmation
   • Soft deletion preserves historical data for deleted player accounts

4. Leaderboard Ranking:

   • Multiplayer games and matches only
   • Ties resolved by earlier achievement date

Notes for Developers

• The WebSocket server acts as the authoritative source for all game state in multiplayer games
• Ensure proper error handling and recovery for WebSocket disconnections
• All coin transactions must be atomic and immutable
• Database must be seeded with realistic, varied data
• Privacy and data protection must be maintained throughout

License

This project is part of the EI – DAD 2025/26 course.