Alchemist's Quest: Developer Guide - Step 1 Repo Restructure

🎯 Objective

Transform the existing single-directory repository into a modern, full-stack application structure by creating separate frontend/ and backend/ directories.

Non-Technical Explainer: This foundational step is known as separation of concerns. Think of it as building two distinct workshops. The frontend/ workshop is where the user-facing magic happens—the interactive journey for the Alchemist. The backend/ workshop is the engine room, managing all the data, logic, and mystical secrets. This separation allows each part to be developed and scaled independently.

In the story, this task is performed by Lab Assistant Sparky, who is "organizing our magical library" and gathering tools. This preparation is essential before the Gordian Mage (our user) can begin to define their "Mystical Quandary".

📋 Prerequisites

Before starting, ensure you have the following:

Access to the project's GitHub repository
Git installed and configured on your local machine
Node.js and npm (or a similar package manager) installed

Note: These prerequisites are based on standard web development practices.

🚀 Sequence of Events and Detailed Tasks

Phase 1: Directory Scaffolding and Content Migration

1. Clone the Repository

Task: Clone the latest version of the main branch to your local development environment.

git clone <repository_url>

2. Create Core Directories

Task: At the root of the project, create two new directories: frontend and backend.

Rationale: This physically separates the codebase for the user-facing interactive experience from the server-side logic and database interactions. It's the first step in creating our two distinct "workshops".

3. Migrate Existing Static Content

Task: Move all existing static content (HTML, CSS, JavaScript files, images) from the root directory into the new frontend/ directory.

Rationale: This consolidates all the code related to what the user sees and interacts with. This folder will eventually house the UI components for the seven steps of the journey, like the "Mystical Quandary" form.

Phase 2: Backend Initialisation and Configuration

1. Initialise the Node.js Backend

Task: Navigate into the backend/ directory and initialise it as a new Node.js project to create a package.json file.

cd backend && npm init -y

Rationale: This officially establishes the backend/ folder as a distinct application with its own list of dependencies and scripts. This package.json file acts as the blueprint for our "engine room," laying the groundwork for the Express backend.

2. Install Essential Backend Dependencies

Task: While inside the backend/ directory, install the core Node.js packages needed for the application.

npm install express mongoose cors jsonwebtoken bcryptjs

Dependency Rationale: These are the magical ingredients Sparky needs for the backend:

express

Web framework for building our API

mongoose

MongoDB interaction assistant

cors

Cross-origin permission middleware

jsonwebtoken

Secure token authentication

bcryptjs

Password hashing security

3. Create Placeholder Backend Directory Structure

Task: Inside backend/, create empty folders for an MVC-style pattern:

controllers/: Logic for handling API requests (e.g., creating a new Quest)
models/: Data schemas (structure for User or Quest)
routes/: API endpoints (addresses like /api/quests)
middleware/: Functions for authentication checks

Rationale: Think of this as setting up labelled shelves in Sparky's library. Establishing this structure now ensures the backend remains organised, scalable, and maintainable as we add more features.

4. Add a .gitignore File

Task: Create a .gitignore file in the root directory to prevent sensitive files and unnecessary folders from being committed to version control.

Rationale: This is a critical security measure. It's like a spell of invisibility that hides secret notes (like API keys) and bulky, auto-generated folders (like node_modules) from being saved in the public repository.

5. Commit and Push the New Structure

Task: Stage, commit, and push all changes to the remote GitHub repository.

git add .
git commit -m "feat: Initialise full-stack repository structure"
git push origin main

✅ Acceptance Criteria

When you are finished, the repository should meet these conditions:

The root directory contains frontend/ and backend/ directories, along with files like .gitignore
All pre-existing static files are now located inside the frontend/ directory
The backend/ directory contains a package.json file listing express, mongoose, cors, jsonwebtoken, and bcryptjs as dependencies
The backend/ directory contains the empty sub-directories: controllers, models, routes, and middleware
The new structure is successfully pushed and visible on the remote GitHub repository

What's Next: Once this repository restructure is complete, you'll be ready to move on to the next steps in the Alchemist's Quest development journey. Each subsequent step will build upon this solid foundation, gradually transforming the separated workshops into a fully functional full-stack application.