FrogHunter Memory game / Milestone 3

README.md

@@ -1,65 +1,188 @@
 # 🐸 Frog Hunter – Memory Game
 
 Frog Hunter is a browser-based memory game developed as part of the **Foundation Project at Hack Your Future**.
+The project explores how a simple, familiar game can be built incrementally while introducing core frontend logic and a basic backend architecture.
 
-The game is inspired by the classic Memory Game and challenges players to find all matching pairs of cards by flipping them two at a time.
-Our focus is on making the game work and building a smooth, intuitive, and enjoyable experience that encourages players to keep playing.
+The game is inspired by the classic Memory game: players reveal cards two at a time and try to find all matching pairs.
+Over the course of the project, the implementation evolves from a purely frontend solution to a full-stack version where card data is served from a backend API.
 
-This project is developed incrementally, following a sprint-based approach, where functionality, structure, and complexity grow step by step.
+This repository reflects that progression and the decisions made along the way.
 
 ---
 
 ## 🎮 About the Game
 
-In Frog Hunter, players interact with a grid of cards showing frog-themed images.
+In Frog Hunter, players interact with a grid of frog-themed cards.
+
+Core mechanics:
 
 - Cards start face down
-- Players flip cards to reveal the images
-- Only two cards can be revealed at the same time
-- Matching cards remain revealed
-- Non-matching cards flip back after a short delay
-- The game ends once all matching pairs have been found
-- The timer starts from when the player clicks their first card
-- The counter shows how many times the player has revealed a card
+- Players can reveal two cards at a time
+- Revealed cards show their image
+- Matching cards disappear from the board and are no longer interactive
+- Not matching cards flip back after a short delay
+- The game ends when all matching pairs are found
+- A timer starts when the first card is revealed
+- A counter tracks how many cards reveals the player has made (a reveal is not the same as a click)
+
+The game logic is intentionally kept clear and predictable, focusing on state management, timing, and user feedback rather than complex visual effects.
+
+---
+
+## 🧠 Development Approach
+
+The project follows a sprint-based, incremental approach:
+
+### 1. Initial version
+
+- Game logic implemented entirely in the frontend
+- Cards hardcoded in JavaScript
+- Focus on DOM manipulation and game state
+
+### 2. Refactored version
 
-Display a timer should start from when the player clicks their first card.
+- Card data moved to a backend API
+- SQLite database introduced for persistence
+- Frontend refactored to fetch card data dynamically
+- Game logic remains fully client-side
 
-The game logic and interactions are designed to be clear, responsive, and easy to understand.
+This separation keeps responsibilities clear:
+
+- **Frontend** → game logic, UI, state, timing
+- **Backend** → data storage and retrieval only
 
 ---
 
-## 🛠️ Technologies & Approach
+## 🛠️ Technologies Used
+
+### Frontend
 
-This project is built using:
+- **HTML** — structure and semantic markup
+- **CSS** — layout, visual styling, and basic responsiveness
+- **JavaScript** — game logic, state handling, and DOM updates
 
-- **HTML** for structure
-- **CSS** for layout and animations
-- **JavaScript** for game logic and DOM manipulation
-- **Git & GitHub** for version control and collaboration
+### Backend
 
-As part of the project milestones, the game evolves from a fully frontend-based implementation to a version that includes:
+- **Node.js** — server runtime
+- **Express.js** — REST API
+- **SQLite** — lightweight relational database for card data
 
-- Fetching card data from a backend API
-- Storing card information in a database
+### Tooling
 
-These steps are introduced progressively as the project advances through the sprints.
+- **Git & GitHub** — version control and collaboration
+- **npm** — dependency management and scripts
+- **Postman** — API testing during development
+- **VS Code** — development environment
+
+---
+
+## 🔌 API Overview
+
+The frontend fetches card data from a backend API.
+
+`GET /cards`
+
+Returns all available cards in JSON format.
+Each card includes:
+
+`- id`
+`- name`
+`- image`
+`- alt`
+`- color`
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "frog1",
+    "image": "Images/frog1.png",
+    "alt": "Frog smiling",
+    "color": "#43bef7"
+  }
+]
+```
+
+The API was manually tested using Postman.
+Valid endpoints return `200 OK`; invalid routes return `404 Not Found`.
+
+---
+
+## ▶️ How to Run the Project
+
+### Backend
+
+```bash
+cd server
+npm install
+npm start
+```
+
+The server runs at:
+
+```arduino
+http://localhost:3000
+```
+
+### Frontend
+
+Open `app/index.html` in your browser.
+The game will fetch card data from the running backend server.
 
 ---
 
 ## 📂 Project Structure
 
-/frogHunter
-│── index.html
-│── styles.css
-│── script.js
+```
+frog hunter/
+├── postman/                                            # Postman tests, collection and API evidence
+|   ├── collection/                                     # Exported Postman collection
+│   ├── screenshots/                                    # Evidence of API responses and test results
+│   │   ├── body-preview.png
+│   │   └── test-results.png
+│   └── postman-tests.md                                # Documentation of Postman test scripts
+|
+├── app/                                                # Frontend application
+| |── Images/                                           # Card images and visual assets
+| │── index.html                                        # Main HTML file
+| │── styles.css                                        # Application styles
+| └── script.js                                         # Frontend logic
+|
+├── server/                                             # Backend
+| ├── package.json                                      # Backend dependencies
+| ├── package-lock.json                                 # Dependency lock file
+| ├── index.js                                          # Express server and API routes
+| ├── database.db                                       # SQLite database
+| └── script-2.sql                                      # Database schema and seed data
+|
+└── README.md                                           # Project overview and setup instructions
+```
+
+The structure is intentionally simple to keep the focus on:
+
+- game logic
+- state management
+- frontend–backend communication
+
+---
+
+## 📝 Notes & Decisions
 
-The structure is intentionally simple, allowing us to focus on core concepts such as game logic, state handling, and user interaction.
+- Card data is no longer hardcoded in the frontend.
+- New cards can be added by updating the database without changing game logic.
+- The backend remains minimal by design.
+- The frontend grid and cards scale with screen size; minor UI refinements are possible for smaller devices.
+- Image assets are credited in the UI.
+- Matched cards are now visually hidden with a smooth animation, providing clear feedback when a pair is found.
+- The 'matched' state ensures cards are both non-interactive and visually removed without affecting game logic or grid layout.
 
 ---
 
 ## 👩🏻‍💻👩🏼‍💻 Team
 
-This project is developed as a pair-programming exercise, emphasizing collaboration, communication, and shared ownership of the codebase:
+This project was developed as a pair-programming exercise, emphasizing collaboration, communication, and shared ownership of the codebase.
 
 - **Paloma Cardozo**
 - **Iryna Lopatina**

app/index.html

@@ -0,0 +1,90 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Frog Hunter - memory game</title>
+    <link rel="icon" type="image/x-icon" href="Images/favicon.ico" />
+    <link rel="stylesheet" href="styles.css" />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+
+  <body>
+    <header class="wrap">
+      <h1>Frog Hunter</h1>
+      <h2>Test Your Memory. Hunt the Frogs.</h2>
+    </header>
+
+    <main class="game wrap">
+      <div class="controls">
+        <div class="controls-main">
+          <button class="button restart-btn">
+            <span class="button-text">Restart</span>
+          </button>
+
+          <div class="state">
+            <div class="moves">Reveals: 0</div>
+            <div class="timer countdown-timer">Time left: 00:00</div>
+          </div>
+        </div>
+
+        <div class="levels">
+          <button class="level-btn active" data-pairs="6">Level 1</button>
+          <button class="level-btn" data-pairs="8">Level 2</button>
+          <button class="level-btn" data-pairs="10">Level 3</button>
+        </div>
+      </div>
+
+      <div class="container"></div>
+
+      <div class="winner">
+        <div class="winner-container">
+          <img
+            src="Images/celebration.png"
+            alt="Frog celebration"
+            class="frog-icon"
+          />
+
+          <p class="winner-title">You won!</p>
+          <p class="winner-moves"></p>
+          <p class="winner-time"></p>
+          <button class="button winner-btn">
+            <span class="button-text">Play again</span>
+          </button>
+        </div>
+      </div>
+
+      <div class="timeout">
+        <div class="timeout-container">
+          <img
+            src="Images/mind-blown.png"
+            alt="Frog mind blown"
+            class="frog-icon"
+          />
+
+          <p class="timeout-title">Oops! Time’s Up</p>
+          <p class="timeout-text">So close!</p>
+          <button class="button timeout-btn">
+            <span class="button-text">Try again</span>
+          </button>
+        </div>
+      </div>
+    </main>
+
+    <footer class="wrap">
+      <div>
+        <p>
+          Stickers created by
+          <a href="https://www.flaticon.com" target="_blank" title="Flaticon"
+            >Flaticon</a
+          >
+        </p>
+      </div>
+    </footer>
+
+    <script src="script.js"></script>
+  </body>
+</html>