FOCCACIA - FOotball Complete Clubs API and Chelas Internet Application

Overview

FOCCACIA is a web application developed as part of the Internet Programming/Introduction to Web Programming course at Instituto Superior de Engenharia de Lisboa. The application provides a RESTful API and a web user interface for managing football competitions, teams, and user-created "Best XI" groups. It integrates with the football-data.org API to fetch real-world football data.

This project is part of the Winter Semester of 2025/2026 – 2nd Practical Assignment (Part 3).

---

Features

Functional Requirements

The FOCCACIA application supports the following features:

1. Competitions

   • Retrieve a list of available competitions, including their code and name.

2. Teams

   • Retrieve teams for a specific competition and season, including:
     • Team name
     • Country
     • Players (name, position, nationality, age)

3. "Best XI" Groups

   • Create a group with a name, description, competition, and year.
   • Edit a group's name and description.
   • List all groups.
   • Delete a group.
   • Retrieve group details, including:
     • Group name, description, competition, and year.
     • List of selected players (playerId, playerName, teamId, teamName, position, nationality, age).
   • Add a player to a group's "Best XI" (maximum of 11 players per group).
   • Remove a player from a group.

4. User Management

   • Create a new user with a username.
   • Authenticate users using a Bearer Token (UUID generated at user creation).

---

Non-Functional Requirements

• Technology Stack:

  • Node.js (ES modules): Backend development with Express 5.
  • Handlebars: Server-side rendering for the web UI.
  • Bootstrap 5.3.3 and Bootstrap Icons 1.11.3: UI styling and icons.
  • Passport: Authentication with local strategy for sessions and bearer tokens for API.
  • Fetch API: HTTP requests to football-data.org.

• Data Storage:

  • Groups and users are stored in memory (default) or Elasticsearch 9.2 for persistence.

• Web UI:

  • Server-rendered pages using Handlebars templates.
  • Responsive design with Bootstrap.

• API Design:

  • RESTful principles with JSON responses.
  • OpenAPI/Swagger documentation.

• Rate Limits:

  • Comply with football-data.org's rate limits (12 requests/minute) with in-memory caching.

---

Project Structure

The server application consists of the following modules:

• src/main/foccacia-server.mjs: Entry point; configures Express, middleware, routes, and starts the server.
• src/main/config/app-config.mjs: Application configuration and environment variables.
• src/main/Data/: Data access layer implementations.
  • foccacia-db-data.mjs: Elasticsearch persistence.
  • foccacia-fapi-data.mjs: Football API integration with caching.
  • foccacia-mem-data.mjs: In-memory storage.
• src/main/Services/foccacia-logic.mjs: Business logic for groups, users, and validations.
• src/main/web/: Web layer.
  • api/: REST API routes.
  • auth/: Authentication routes and Passport configuration.
  • routes/: General web routes.
  • ui/: UI handlers for rendering pages.
• src/main/error/foccacia-error.mjs: Error handling utilities.
• src/main/utils/foccacia-utils.mjs: General utilities and logging.
• views/: Handlebars templates for server-side rendering.
• public/: Static assets (CSS, JS, images).
• test/: Unit and integration tests with Mocha and Chai.
• docs/: Documentation, API specs, and diagrams.

---

Development Methodology

1. API Design:

   • Define and document API routes using OpenAPI/Swagger.
   • Create REST Client requests to test API routes.

2. Incremental Development:

   • Implement routes in foccacia-web-api.mjs one by one.
   • Test each route using REST Client before proceeding to the next.

3. Unit Testing:

   • Write unit tests for foccacia-services.mjs using Mocha and Chai.
   • Mock external dependencies (e.g., API Football) during testing.

4. Data Access:

   • Implement fapi-teams-data.mjs for API Football integration.
   • Implement foccacia-data-mem.mjs for in-memory data storage.

---

API Documentation

• OpenAPI Specification:

  • File: docs/foccacia-api-spec.yaml
  • Describes all API endpoints, request/response formats, and authentication requirements.

• REST Client Requests:

  • Folder: requests
  • Contains HTTP requests for testing the API using the REST Client plugin in Visual Studio Code.

---

How to Run

1. Install Dependencies:

   npm install

2. Set Environment Variables: Create a .env file with the following variables:

   # Port where the Express application runs
   PORT=
   # API key for accessing the football data API
   FOOTBALL_API_KEY=
   # Environment setting (development/production)
   NODE_ENV=
   # Data scheme to use (db/mem)
   DATA=
   # Database host (Elasticsearch)
   DB_HOST=
   

3. Populate db if needed:

   npm run createDbData

4. Run Unit Tests:

   npm test

5. Start the Server:

   npm start

6. Access the Web UI:

   • Open a browser and navigate to http://localhost:<PORT> (replace with the value from your .env file).
   • Register a new user or log in to manage groups and explore competitions.

7. Test the API:

   • Use the REST Client file docs/http/foccacia-api-requests.http to test the API.
   • Include the Bearer token from user registration in API requests.

---

Example Endpoints

1. Get Competitions:

   • GET /competitions
   • Response:

     [
       { "code": "PL", "name": "Premier League" },
       { "code": "CL", "name": "Champions League" }
     ]

2. Create Group:

   • POST /groups
   • Request Body:

     {
       "name": "My Best XI",
       "description": "Favorite players from PL 2024",
       "competition": "PL",
       "year": 2024
     }

3. Add Player to Group:

   • POST /groups/{groupId}/{playerId}
   • Response:

     { "message": "Player added successfully" }

---

Resources

• football-data.org Documentation
• Node.js Documentation
• Express Documentation

---

Authors

• Rafael Pereira (52880)
• Ian Frunze (52867)
• Tito Silva (53118)
• Group Name: LEIC2526i-IPW32D-G01
• Course: Internet Programming/Introduction to Web Programming
• Institution: Instituto Superior de Engenharia de Lisboa
• Semester: Winter 2025/2026