Empowering Australian Teens (12-18) with AI-Powered Investment Education
A gamified investment education platform that takes players on a journey through financial history, from the Japanese Bubble Economy (1990) to current market challenges, teaching real investment strategies through interactive missions and AI-powered coaching.
Legacy Guardians is an innovative educational game designed specifically for Australian teenagers aged 12-18. Players navigate through major financial events in history, make investment decisions, and learn from AI coaches while competing in real-time investment competitions.
- 📚 Historical Financial Missions: Journey through 35+ years of financial history
- 🤖 AI-Powered Coaching: Personalized investment advice from specialized AI coaches
- 📊 Real-Time Trading Simulation: Practice with $1,000 virtual capital
- 🏆 Competitive Leaderboards: Compete with players globally
- 📈 Advanced Analytics: Performance charts and risk analysis
- 🎮 Gamified Learning: XP system, achievements, and progressive unlocking
- 🎁 Real Rewards System: Exchange XP for Australian brand gift cards with QR codes
- Node.js 18+
- Python 3.8+
- npm or yarn
- Git
git clone <repository-url>
cd financial-timeline-gameCreate a .env.local file in the root directory:
# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000
# OpenAI API Key (for AI Coach functionality)
OPENAI_API_KEY=your_openai_api_key_hereCreate a .env file in the backend directory for email functionality:
# Email Configuration (Optional - see backend/EMAIL_SETUP.md)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SENDER_EMAIL=your-email@gmail.com
SENDER_PASSWORD=your_app_password
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key
# Debug Mode
DEBUG=falseFrontend:
npm install
# or if you encounter dependency issues:
npm install --legacy-peer-depsBackend:
cd backend
pip install -r requirements.txt
cd ..Start Backend:
./start_backend.shStart Frontend (in a new terminal):
npm run dev- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
- Start with the Japanese Bubble Economy (1990)
- Complete missions chronologically to unlock new events
- Make investment decisions based on historical context
- Learn from AI coaches about market dynamics
- Unlock after completing all historical missions
- Allocate your $1,000 starting capital across various assets
- Choose from 4 specialized AI coaches
- Trade in real-time with market simulation
- View detailed performance charts
- Analyze risk metrics (Sharpe ratio, volatility, max drawdown)
- Compare your results with global leaderboards
- Earn XP and achievements
- Framework: Next.js 14 with TypeScript
- UI Components: shadcn/ui with Tailwind CSS
- Charts: Recharts for data visualization
- State Management: React hooks and context
- Framework: FastAPI with Python
- Database: SQLite with thread-safe connections
- AI Integration: OpenAI API for coaching
- Data Generation: Mock market data with realistic trends
components/
├── PerformanceChart.tsx # Investment performance visualization
├── AICoach.tsx # AI coaching interface
├── investment-competition.tsx # Competition setup
├── trading-dashboard.tsx # Real-time trading interface
└── competition-results.tsx # Results and leaderboards
backend/
├── main.py # FastAPI application
├── models.py # Pydantic data models
├── database.py # Database management
└── services/ # Business logic services
# Development
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint
# Backend
./start_backend.sh # Start FastAPI backendGET /health- Health checkGET /events- Get financial eventsGET /prices- Get market price dataPOST /simulate- Simulate investment returnsPOST /coach/advice- Get AI coaching adviceGET /leaderboard- Get competition rankingsPOST /rewards/redeem- Redeem XP for rewards (with email delivery)
| Variable | Description | Required |
|---|---|---|
NEXT_PUBLIC_API_URL |
Backend API URL | Yes |
OPENAI_API_KEY |
OpenAI API key for AI coaching | Yes |
Backend Email Variables (Optional - for email functionality):
| Variable | Description | Required |
|---|---|---|
SMTP_SERVER |
SMTP server (e.g., smtp.gmail.com) | No |
SMTP_PORT |
SMTP port (usually 587) | No |
SENDER_EMAIL |
Email address for sending | No |
SENDER_PASSWORD |
App password for email service | No |
- Japanese Bubble Economy Collapse (1990)
- Asian Financial Crisis (1997)
- Dot-com Bubble Burst (2000)
- Global Financial Crisis (2008)
- COVID-19 Market Crash (2020)
- Current Challenges (2025)
- Stocks: Apple, Microsoft, NVIDIA, Tesla
- ETFs: S&P 500, Global Diversified
- Cryptocurrency: Bitcoin, Ethereum
- Steady Sam (Conservative): Risk control and stable returns
- Balanced Bella (Balanced): Optimal risk-return balance
- Adventure Alex (Aggressive): High returns, high risk
- Tech Taylor (Tech-focused): AI and technology trends
- Australian Brand Partners: JB Hi-Fi, Guzman y Gomez, Boost Juice, etc.
- XP Exchange: Convert earned XP to gift cards
- QR Code Delivery: Instant voucher delivery via email with scannable QR codes
- Mobile Optimized: Easy redemption at partner locations
- Total Return: Overall portfolio performance
- Sharpe Ratio: Risk-adjusted returns
- Volatility: Portfolio risk measurement
- Max Drawdown: Maximum loss from peak
- Annualized Return: Yearly performance rate
# Build frontend
npm run build
# Set production environment variables
NEXT_PUBLIC_API_URL=https://your-api-domain.com
OPENAI_API_KEY=your_production_api_key
# Start production server
npm start- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Built for NextGen AI Hackathon 2025
- Designed for Australian teenagers aged 12-18
- Powered by OpenAI's GPT models for AI coaching
- Inspired by real financial market events
Start your investment journey today! 🚀💰