PROJECT OVERVIEW:
The application, tentatively named 'Kadim Bilgelik: Evrimsel Zeka Rehberi' (Ancient Wisdom: Evolutionary Intelligence Guide), aims to be an AI-powered educational and simulation platform. It delves into the survival strategies and learning processes of early humans, particularly focusing on species like Neanderthals and Homo Erectus, to enhance modern human decision-making and problem-solving skills. The core value proposition is to provide an engaging and insightful way to learn about human evolution, offering practical applications for contemporary challenges through interactive simulations and AI-driven analysis of historical survival tactics. The platform addresses the modern need for deeper understanding of human adaptability and cognitive development by drawing parallels between past survival pressures and present-day decision-making scenarios.
TECH STACK:
- Frontend Framework: React.js (using Create React App for simplicity in MVP)
- Styling: Tailwind CSS for rapid UI development and a consistent design system.
- State Management: Zustand for efficient and straightforward global state management.
- Routing: React Router DOM for navigation within the single-page application.
- Data Fetching/API: Axios for HTTP requests if an API is introduced later. For MVP, mock data will be used and managed via Zustand.
- Animation Library: Framer Motion for smooth and interactive UI animations.
- Icons: React Icons for a variety of readily available icons.
CORE FEATURES:
1. Interactive Evolutionary Timeline & Maps:
* User Flow: Upon landing, users see a visually appealing timeline spanning from early hominins to Homo Sapiens. They can navigate this timeline. Clicking on specific periods (e.g., Neanderthal era, Homo Erectus migration) zooms into an interactive map displaying key geographical locations, environmental conditions, and significant evolutionary milestones relevant to that period. Tooltips provide brief context on hover.
* Details: The timeline should be scrollable horizontally. Maps should be zoomable and pannable. Key events are marked with distinct icons.
* Data: Requires structured data for events, locations, environmental data (temperature, flora/fauna), and species distribution over time.
2. Scenario-Based Survival Simulations:
* User Flow: Users select a specific era or challenge (e.g., 'Neanderthal Winter Survival', 'Homo Erectus Resource Scarcity'). They are presented with a scenario (e.g., "A harsh winter is approaching. Your tribe has limited stored food and tools. What is your priority?"). They choose from multiple-choice options (e.g., 'Focus on hunting larger game', 'Ration existing food supplies', 'Seek warmer shelter'). The system simulates the outcome based on predefined logic and presents the consequences (e.g., 'Successful hunt, but high risk. Tribe's food stores are replenished, but injuries occurred.', or 'Rationing led to starvation. Focus shifts to finding new resources.'). Feedback explains the evolutionary implications of the choice.
* Details: Scenarios should be concise, impactful, and directly related to evolutionary pressures. Outcomes should provide clear feedback.
* Data: Scenarios, choices, outcome logic (can be simple probability-based or rule-based for MVP), and consequence descriptions.
3. Knowledge Base & Learning Modules:
* User Flow: A dedicated section where users can access bite-sized information modules about human evolution, anthropology, and evolutionary psychology. Categories could include 'Tool Use Evolution', 'Social Structures', 'Cognitive Development'. Each module consists of text, images, and potentially short animations or interactive elements.
* Details: Content should be accurate, easily digestible, and engaging. Search functionality could be a future enhancement.
* Data: Articles, categorized content, associated media.
4. User Profile & Progress Tracking:
* User Flow: Users can create a simple profile (email/password or social login - MVP will use local state for simplicity). Their progress in completing modules and simulations is tracked. A dashboard displays completed modules, simulation performance scores, and earned badges (e.g., 'Master Navigator', 'Survival Expert').
* Details: Gamification elements like badges motivate users. Progress visualization is key.
* Data: User ID, completed modules, simulation history, earned badges.
UI/UX DESIGN:
- Layout: A clean, modern, and intuitive single-page application layout. A persistent sidebar or top navigation bar for accessing main sections (Timeline, Simulations, Knowledge Base, Profile). The main content area dynamically updates based on user selection. Ample whitespace.
- Color Palette: Earthy tones combined with modern, clean accents. Primary: Deep ochre (#B06500), Secondary: Forest green (#228B22), Accent: Sky blue (#87CEEB), Text: Dark grey (#333333), Background: Off-white (#F8F8F8).
- Typography: A sans-serif font family like 'Inter' or 'Roboto' for readability. Clear hierarchy using font weights and sizes (e.g., H1, H2, body text, captions).
- Responsive Design: Mobile-first approach. Tailwind CSS's responsive prefixes (sm:, md:, lg:) will be used extensively. Navigation collapses into a hamburger menu on smaller screens. Content blocks reflow and resize appropriately. Ensure touch targets are adequately sized.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global layout.
- `Navigation.js`: Persistent sidebar/header component with links to different sections. Handles active link styling.
* Props: `routes` (array of route objects).
- `Timeline.js`: Displays the interactive evolutionary timeline. Handles zooming and panning.
* Props: `eventsData` (array of event objects).
* State: `currentZoom`, `scrollPosition`.
- `MapComponent.js`: Renders the interactive map for a selected era.
* Props: `locations` (array of location objects), `era` (string).
- `SimulationSelector.js`: Lists available survival simulations.
* Props: `simulations` (array of simulation objects), `onSelectSimulation` (function).
- `SimulationRunner.js`: Manages the state and flow of a selected simulation.
* Props: `simulationId` (string), `scenario` (object), `onSubmitChoice` (function).
* State: `currentStep`, `userChoice`, `simulationResult`.
- `KnowledgeBase.js`: Container for learning modules.
- `ModuleList.js`: Displays a list of available learning modules.
* Props: `modules` (array of module objects).
- `ModuleDetail.js`: Displays the content of a single learning module.
* Props: `module` (object).
- `Profile.js`: Displays user progress, badges, and stats.
- `Badge.js`: Displays a single badge icon and name.
* Props: `badge` (object).
- `Common/Tooltip.js`: Reusable tooltip component.
- `Common/Button.js`: Reusable button component with styling variants.
- `Common/LoadingSpinner.js`: Component for displaying loading states.
DATA MODEL (using Zustand for state management):
- `useTimelineStore`: Manages timeline data, current zoom level, and scroll position.
* `events`: Array of event objects { id, name, date, description, geoLocation, icon }.
* `mapData`: Object containing map-specific data for eras.
* `currentZoom`, `scrollPosition`.
- `useSimulationStore`: Manages simulation data, current scenario, user choices, and results.
* `simulations`: Array of simulation definitions.
* `currentSimulationId`, `currentScenarioIndex`, `simulationResults`.
* `selectSimulation(id)`, `submitChoice(choice)`, `resetSimulation()`.
- `useKnowledgeStore`: Manages knowledge base content.
* `modules`: Array of module objects { id, title, content, category, image }.
* `selectedModuleId`.
- `useUserStore`: Manages user profile and progress.
* `userId`, `email` (optional for MVP), `completedModules`: Set of module IDs, `simulationHistory`: Array of simulation results, `earnedBadges`: Array of badge IDs.
* `login()`, `completeModule(moduleId)`, `recordSimulationResult(result)`.
SAMPLE DATA:
1. Event Data (`events` in `useTimelineStore`):
```json
[
{ "id": "aurignacian", "name": "Aurignacian Culture Emerges", "date": "-40000", "description": "Early Upper Paleolithic culture associated with Homo sapiens in Europe.", "geoLocation": { "lat": 48.8566, "lng": 2.3522 }, "icon": "star" },
{ "id": "neanderthal_extinction", "name": "Neanderthal Extinction", "date": "-35000", "description": "Decline and eventual extinction of Neanderthal populations.", "geoLocation": { "lat": 45.0, "lng": 15.0 }, "icon": "skull" },
{ "id": "homo_erectus_fire", "name": "Controlled Use of Fire", "date": "-500000", "description": "Evidence suggests Homo Erectus began controlling fire.", "geoLocation": { "lat": 30.0, "lng": 35.0 }, "icon": "flame" }
]
```
2. Simulation Definitions (`simulations` in `useSimulationStore`):
```json
[
{ "id": "neanderthal_winter", "title": "Neanderthal Winter Survival", "description": "Survive a harsh Ice Age winter.", "scenarios": [ { "id": 1, "prompt": "A blizzard is approaching. Your cave is drafty. What's the priority?", "choices": [ { "text": "Reinforce cave insulation", "outcome": "Success: Reduced cold exposure. Tribe morale boosted." }, { "text": "Hunt for extra warm pelts", "outcome": "Partial Success: Got some pelts but lost valuable time. Risk of getting lost." } ] } ] },
{ "id": "erectus_migration", "title": "Homo Erectus Migration", "description": "Find new hunting grounds.", "scenarios": [ /* ... scenarios ... */ ] }
]
```
3. Module Data (`modules` in `useKnowledgeStore`):
```json
[
{ "id": "tool_evolution", "title": "Evolution of Stone Tools", "category": "Technology", "content": "Early hominins like Homo Habilis developed Oldowan tools...", "image": "/images/tools.jpg" },
{ "id": "social_structures", "title": "Early Social Structures", "category": "Sociology", "content": "Evidence suggests group living provided protection and facilitated resource sharing...", "image": "/images/group.jpg" }
]
```
4. User Data (`useUserStore` - initially empty):
```json
{
"userId": "user_123",
"completedModules": [],
"simulationHistory": [],
"earnedBadges": []
}
```
5. Badge Data (example):
```json
{ "id": "survival_expert", "name": "Survival Expert", "icon": "award" }
```
ANIMATIONS & INTERACTIONS:
- Page Transitions: Subtle fade-in/fade-out transitions between sections using Framer Motion (`AnimatePresence`).
- Hover Effects: Buttons and interactive elements will have slight scale or background color changes on hover. Timeline markers and map points will subtly pulse or scale up.
- Loading States: When fetching data (even mock data for simulation setup), display a `LoadingSpinner` component. Map tiles or complex timeline elements could have skeleton loaders.
- Micro-interactions: Smooth scrolling on the timeline. Button press feedback. Successful simulation outcome might trigger a subtle celebratory animation.
- Map Interactions: Smooth zoom (e.g., pinch-to-zoom on touch devices, scroll wheel on desktop) and panning. Smooth transitions when changing eras or zooming to specific points.
EDGE CASES:
- Empty States: Display user-friendly messages when no simulations are available, no modules are found, or the user profile is empty (e.g., "No simulations found for this era. Check back later!", "Start learning by exploring our modules.").
- Error Handling: Implement basic error boundaries in React. If data fetching fails (in a future API scenario), display a clear error message. For simulations, if an unexpected error occurs during outcome calculation, show a generic error message and allow the user to restart.
- Validation: If user input is added (e.g., profile creation), implement simple client-side validation (e.g., email format).
- Accessibility (a11y): Ensure sufficient color contrast. Use semantic HTML elements. Add ARIA attributes where necessary (e.g., `aria-label` for icon buttons). Ensure keyboard navigability for all interactive elements. Alt text for images.
DEPLOYMENT NOTES:
- Build: Use `npm run build` or `yarn build`. Ensure the output is optimized for static hosting.
- Environment Variables: For MVP, none are strictly required. For future API integration, use `.env` files (`REACT_APP_API_URL`).
- Performance Optimizations: Code splitting using React.lazy and Suspense for different sections/pages. Optimize images. Use memoization (React.memo, useMemo, useCallback) where performance bottlenecks are identified. Ensure efficient state updates with Zustand.
- Hosting: Suitable for static hosting platforms like Netlify, Vercel, or GitHub Pages.