AETHERIA

AETHERIA is a gamified productivity and habit-tracking platform inspired by the magical world of Hogwarts.

The main goal of this project is to help users turn their daily goals and habits into quests that can be completed to earn XP, maintain streaks, level up, and contribute points to their chosen house. Users can also activate spells, craft potions, view their statistics, and compete through the House Cup and Wizard Leaderboard.

Architecture

                         AETHERIA
                            │
             ┌──────────────┴──────────────┐
             │                             │
        React Frontend                Express Backend
             │                             │
       React + Vite                    REST API
       Tailwind CSS                       │
       React Router                       │
       Axios                              │
             │                             │
             └──────────────┬──────────────┘
                            │
                         MongoDB
                            │
                         Mongoose

FEATURES

🧙 User Authentication — Secure registration and login using JWT authentication
🏰 House Selection — Choose between Gryffindor, Ravenclaw, Slytherin, and Hufflepuff
⚔️ Quest System — Create, update, complete, fail, and delete personal quests
⭐ XP & Level System — Earn XP from completed quests and level up
🔥 Daily Streaks — Maintain activity streaks through consistent quest completion
❤️ HP System — Completing quests restores HP while failing quests reduces it
🧪 Potion System — Unlock special XP multipliers through quest combinations
✨ Spell System — Activate temporary productivity spells
🦉 Daily Owl — Receive productivity suggestions based on recent activity
🏆 House Cup — Houses compete through accumulated points
🧙‍♂️ Wizard Leaderboard — Users are ranked according to their XP
📊 Statistics Dashboard — Track XP history, completed quests, house activity, and active abilities
👤 Profile Management — View and update user information
📱 Responsive UI — Designed to work across different screen sizes

🛠️ Tech Stack

Frontend

React.js
TypeScript
Vite
Tailwind CSS
React Router
Axios
Lucide React
clsx

Backend

Node.js & Express.js
TypeScript
MongoDB & Mongoose
JWT — Authentication & authorization
bcryptjs — Password hashing
express-validator — Request validation
CORS
dotenv

Database

MongoDB
Mongoose ODM

📁 Project Structure

project-root/
├── frontend/
├── backend/
├── shared/
├── package.json
└── README.md

Frontend

frontend/
└── src/
    ├── components/
    │   ├── ui/
    │   ├── HouseCard.tsx
    │   ├── LoadingScreen.tsx
    │   ├── Navbar.tsx
    │   ├── ProtectedRoute.tsx
    │   ├── QuestCard.tsx
    │   ├── StatChip.tsx
    │   ├── Toast.tsx
    │   └── XPBar.tsx
    │
    ├── context/
    │   ├── AuthContext.tsx
    │   ├── QuestContext.tsx
    │   └── ToastContext.tsx
    │
    ├── pages/
    │   ├── DashboardPage.tsx
    │   ├── Home.tsx
    │   ├── HouseSelectionPage.tsx
    │   ├── LeaderboardPage.tsx
    │   ├── LoginPage.tsx
    │   ├── ProfilePage.tsx
    │   ├── QuestsPage.tsx
    │   ├── RegisterPage.tsx
    │   └── SpellsPage.tsx
    │
    ├── lib/
    │   └── axios.ts
    │
    ├── App.tsx
    ├── main.tsx
    └── index.css

Backend

backend/
├── src/
│   ├── controllers/
│   │   ├── authController.ts
│   │   ├── houseController.ts
│   │   ├── leaderboardController.ts
│   │   ├── owlController.ts
│   │   ├── questController.ts
│   │   ├── spellController.ts
│   │   ├── statsController.ts
│   │   └── userController.ts
│   │
│   ├── models/
│   │   ├── HouseCup.ts
│   │   ├── Potion.ts
│   │   ├── Quest.ts
│   │   ├── Spell.ts
│   │   └── User.ts
│   │
│   ├── routes/
│   │   ├── auth.ts
│   │   ├── houses.ts
│   │   ├── leaderboard.ts
│   │   ├── owl.ts
│   │   ├── quests.ts
│   │   ├── spells.ts
│   │   ├── stats.ts
│   │   └── users.ts
│   │
│   ├── middleware/
│   │   ├── auth.ts
│   │   └── errorHandler.ts
│   │
│   ├── types/
│   │   └── index.ts
│   │
│   └── server.ts
│
├── package.json
└── tsconfig.json

Shared

shared/
└── package.json

⚔️ Quest & XP System

Users can create quests and assign them to one of the four houses.

Each quest contains:

Title
House
XP Reward
Type
Due Date
Status

Available quest types:

daily
trial
exam

Quest statuses:

pending
completed
failed

When a quest is completed:

Quest Completed
      │
      ├── XP awarded
      ├── Level updated
      ├── HP increased
      ├── Streak updated
      └── House Cup points increased

🏰 Houses

🦁 Gryffindor

Focused around:

Bravery
Courage
Daring
Nerve
Chivalry

🦅 Ravenclaw

Focused around:

Intelligence
Wit
Wisdom
Creativity
Learning

🐍 Slytherin

Focused around:

Ambition
Cunning
Leadership
Resourcefulness

🦡 Hufflepuff

Focused around:

Loyalty
Patience
Hard Work
Fairness
Kindness

🧪 Potions

AETHERIA contains a potion system that rewards users for completing different types of quests.

Completing both Gryffindor and Ravenclaw quests on the same day can unlock a:

🧪 Focus Potion

The Focus Potion provides a 2× XP multiplier when applied to a quest.

✨ Spells

Users can activate temporary spells to represent different productivity modes.

Available spell types:

focus_charm
grind_spell
shield_spell
wingardium

Each spell can be activated for a configurable duration.

The system ensures that only one active spell is maintained for a user at a time.

🦉 Daily Owl

The Daily Owl analyzes recent user activity and provides productivity suggestions.

It checks:

Recent quest completion
Neglected houses
Current streak
Today's completed quests
Potion availability

The system can generate:

Suggested quests
Streak warnings
Potion availability information
Motivational quotes

🏆 Leaderboards

House Cup

Houses compete by accumulating points through completed quests.

Gryffindor ──────┐
Ravenclaw ────────┤
Slytherin ────────┼──► House Cup
Hufflepuff ───────┘

Wizard Leaderboard

Individual users are ranked according to their XP.

The leaderboard displays:

Rank
Username
House
Level
XP

📊 Statistics

Users can track their productivity through:

Quests completed today
Total quests completed
XP history
XP earned by house
Quest distribution by house
Active potion
Active spell

The XP history endpoint also provides daily XP data for the previous 30 days.

🔐 Authentication

AETHERIA uses JWT-based authentication.

Register / Login
       │
       ▼
   JWT Token
       │
       ▼
Frontend Storage
       │
       ▼
Authorization Header
       │
       ▼
Auth Middleware
       │
       ▼
Protected API

Passwords are hashed using bcryptjs before being stored in MongoDB.

Protected endpoints require:

Authorization: Bearer <token>

🚀 Getting Started

Prerequisites

Make sure you have:

Node.js
npm
MongoDB

installed on your system.

Clone the repository

git clone <repository-url>
cd AETHERIA

Install dependencies

npm run install-all

Or install them individually:

cd backend
npm install

cd ../frontend
npm install

Environment Variables

Create a .env file inside backend/:

PORT=5001
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=7d
FRONTEND_URL=http://localhost:5173

Create a .env file inside frontend/ if required by your API configuration:

VITE_API_URL=http://localhost:5001/api

Run the project

Start the backend:

cd backend
npm run dev

Start the frontend:

cd frontend
npm run dev

The application will be available at:

Frontend → http://localhost:5173
Backend  → http://localhost:5001

📜 Available Scripts

Frontend

npm run dev
npm run build
npm run lint
npm run preview

Backend

npm run dev
npm run build
npm run start

🤝 Contributing

Contributions, suggestions, feature requests, and issue reports are welcome.

# Fork → clone → create branch → push → open PR

git checkout -b feature/your-feature-name

Please create a separate branch for each feature or fix and open a pull request when your changes are ready.

Author

Aarsh-HV

⭐ If you like the project

Give the repository a ⭐ and feel free to contribute!

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
backend		backend
frontend		frontend
shared		shared
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

AETHERIA

Architecture

FEATURES

🛠️ Tech Stack

Frontend

Backend

Database

📁 Project Structure

Frontend

Backend

Shared

⚔️ Quest & XP System

🏰 Houses

🦁 Gryffindor

🦅 Ravenclaw

🐍 Slytherin

🦡 Hufflepuff

🧪 Potions

✨ Spells

🦉 Daily Owl

🏆 Leaderboards

House Cup

Wizard Leaderboard

📊 Statistics

🔐 Authentication

🚀 Getting Started

Prerequisites

Clone the repository

Install dependencies

Environment Variables

Run the project

📜 Available Scripts

Frontend

Backend

🤝 Contributing

Author

⭐ If you like the project

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages