PROJECT OVERVIEW:
The core problem this application addresses is the 'comfortable drift toward not understanding what you're doing,' particularly prevalent in academic research and complex technical fields. Researchers, especially students guided by supervisors, can get lost in executing tasks without grasping the underlying principles or the 'why' behind their work. This leads to a lack of true understanding, reduced innovation, and difficulty in reproducing or building upon results. The application, 'Bilge Yol' (Wise Path), is a SaaS platform designed to combat this by providing AI-powered tools that facilitate deep understanding, reproducibility, and genuine scientific contribution. It acts as an intelligent research assistant, guiding users through complex analysis pipelines, explaining intricate concepts, and ensuring the integrity of their research process. The value proposition is to transform research from a task-execution process into a profound learning and discovery journey, fostering the development of truly competent scientists and researchers.
TECH STACK:
- Frontend: React.js (using Create React App or Vite for faster development)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and scalable global state management, especially for complex application states.
- Routing: React Router DOM for client-side navigation.
- UI Components: Radix UI for accessible and unstyled primitives, which will be styled with Tailwind CSS.
- Icons: Heroicons or Lucide React for a clean and consistent icon set.
- Code Editor/Display: Monaco Editor (if complex code interaction is needed) or simply pre-formatted code blocks with syntax highlighting (e.g., using Prism.js or Highlight.js).
- Charting: Chart.js or Recharts for data visualization.
- API Calls: Axios for making HTTP requests to a potential future backend, or to mock API endpoints for MVP.
- Local Storage: Utilized for persisting user preferences, draft states, and potentially small datasets or configurations.
CORE FEATURES:
1. **Project Management & Tracking**:
* **User Flow:** User logs in, navigates to 'Projects' dashboard. Clicks 'New Project'. Enters project title, description, and optionally assigns students (if team features are implemented in MVP). Sets milestones or initial tasks. Views a list of their projects. Clicks on a project to see its details, including assigned tasks, progress status, and meeting notes.
* **Functionality:** Create, read, update, delete (CRUD) operations for projects. Task assignment, status updates (e.g., 'To Do', 'In Progress', 'Blocked', 'Completed'). A dedicated section for weekly meeting notes with AI summarization capability.
2. **Analysis Pipeline Builder (AI-Assisted)**:
* **User Flow:** Within a project, user clicks 'Build Analysis Pipeline'. Chooses a general research area (e.g., 'Galaxy Clustering Data Analysis'). The AI suggests a typical pipeline (e.g., Data Ingestion -> Preprocessing -> Feature Extraction -> Model Training -> Evaluation -> Visualization). User can add, remove, reorder steps. For each step, AI can suggest relevant tools, libraries (e.g., Python: Pandas, Scikit-learn), and code snippets. User can elaborate on specific parameters or goals for each step.
* **Functionality:** AI generates a structured workflow based on user input and general scientific best practices. Provides templates and suggestions. Allows customization of each step. Links suggested tools and libraries to documentation or relevant code examples.
3. **Code & Result Reproducibility Tool**:
* **User Flow:** User uploads a code file (e.g., `analyze.py`) and optionally a dataset or configuration file. The system runs the code in a sandboxed environment (or simulates it for MVP). Displays the output (console logs, generated files, plots). User can view the executed code, its parameters, and the resulting visualizations/data. A 'Reproduce' button allows tweaking parameters (e.g., random seeds, thresholds) and re-running to see variations, confirming reproducibility.
* **Functionality:** Code execution environment simulation. Parameter input interface. Visualization of outputs (plots, tables). Versioning of code runs and their results. Comparison tool for different runs.
4. **Understanding Module (AI-Assisted)**:
* **User Flow:** While viewing a piece of code, a complex equation, or a statistical concept within the platform, the user highlights the relevant section and clicks 'Explain'. The AI provides a clear, step-by-step explanation tailored to the user's likely knowledge level (inferred from their project context or profile). It can break down jargon, explain mathematical formulas, and link to foundational concepts or papers. For example, explaining a specific statistical test used in the code.
* **Functionality:** AI-powered natural language processing and generation. Context-aware explanations. Ability to define terms, summarize complex algorithms, and connect concepts to the broader research context.
5. **Library & Dataset Management**:
* **User Flow:** Within a project, users can access a 'Resources' tab. Here, they can upload datasets (e.g., CSV, JSON), link to external data sources, or list required software libraries/versions (e.g., `requirements.txt` for Python). The system tracks which resources belong to which project.
* **Functionality:** Simple file upload and management. Versioning of uploaded datasets. Metadata storage (description, source, format). Tracking dependencies for reproducibility.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) with a primary navigation sidebar (Projects, Analysis Hub, Resources, Settings). Main content area displays the selected section. Within the Project view, a tabbed or multi-pane layout for Overview, Tasks, Pipeline, Code, Meeting Notes. Clean, uncluttered interface.
- **Color Palette:** Professional and calming. Primary: Deep Blue (#1E3A8A), Secondary: Light Gray (#F3F4F6), Accent: Teal (#14B8A6) for interactive elements and calls to action. Error/Warning: Red/Yellow. Neutral: White/Black for text and backgrounds.
- **Typography:** Sans-serif font family like Inter or Roboto for readability. Clear hierarchy using font weights and sizes (e.g., H1 for page titles, H2 for section titles, body text for content).
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows gracefully. Interactive elements are large enough for touch targets. Tables might become scrollable or stack vertically.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global layout.
- `Layout.js`: Contains the main structure (Sidebar, Header, Content Area).
- `Sidebar.js`: Navigation menu component. Receives `routes` array as props. Manages active link state.
- `ProjectList.js`: Displays a list of projects. Receives `projects` array. Renders `ProjectCard.js` for each.
- `ProjectCard.js`: Displays summary info for a single project. Receives `project` object. Links to `ProjectDetailsPage`.
- `ProjectDetailsPage.js`: Main component for a single project. Fetches/manages project data. Contains tabs for different sections.
- `AnalysisPipelineBuilder.js`: Manages the AI-assisted pipeline creation flow. Uses state for pipeline steps.
- `CodeReproducibilityTool.js`: Handles code upload, execution (simulated), and output display.
- `UnderstandingModule.js`: Interface for highlighting text and triggering AI explanations.
- `ResourceLibrary.js`: Manages uploading and displaying datasets and library requirements.
- `MeetingNotes.js`: Text area for notes, with AI summarization button.
- `Button.js`: Reusable button component with variants (primary, secondary, destructive). Accepts `onClick`, `children`, `variant` props.
- `Input.js`, `TextArea.js`, `Select.js`: Reusable form input components styled with Tailwind.
- `Modal.js`: Generic modal component for confirmations or detailed views.
- `Spinner.js`: Loading indicator component.
DATA MODEL:
- `projects`: Array of project objects.
```json
{
"id": "proj_123",
"title": "Galaxy Clustering Analysis",
"description": "Measuring Baryon Acoustic Oscillations using SDSS data.",
"status": "In Progress",
"students": ["Alice", "Bob"],
"createdAt": "2023-10-26T10:00:00Z",
"updatedAt": "2023-10-26T10:00:00Z",
"tasks": [...],
"pipeline": {...},
"codeRuns": [...] // List of code execution records
}
```
- `tasks`: Array of task objects associated with a project.
```json
{
"id": "task_abc",
"projectId": "proj_123",
"title": "Reproduce Paper X Results",
"description": "",
"status": "Blocked", // 'To Do', 'In Progress', 'Blocked', 'Completed'
"dueDate": "2024-01-15"
}
```
- `codeRuns`: Array of code execution records.
```json
{
"id": "run_xyz",
"projectId": "proj_123",
"codeFile": "// Code content here or reference",
"parameters": {"seed": 42, "threshold": 0.5},
"output": "Console logs, generated plots (URLs), data files (URLs)",
"timestamp": "2023-10-26T11:30:00Z"
}
```
- `resources`: Array of resources (datasets, libraries) linked to projects.
```json
{
"id": "res_def",
"projectId": "proj_123",
"name": "SDSS DR16 Galaxy Data",
"type": "Dataset", // 'Dataset', 'Library', 'Link'
"location": "/data/sdss_dr16.csv" // or URL
}
```
- **State Management:** Zustand will manage `projects`, `currentProject`, `user`, `isLoading`, `error` states globally. Local component state will be used for form inputs, UI toggles etc.
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on buttons and interactive cards.
- **Transitions:** Smooth transitions for route changes (e.g., fade-in/out). Panel expansion/collapse animations. Smooth appearance of new elements (e.g., adding a pipeline step).
- **Loading States:** Use `Spinner.js` component. Skeleton loaders for lists and tables while data is being fetched. Disable buttons and show spinners during critical operations (e.g., code execution).
- **Micro-interactions:** Visual feedback on successful form submission (e.g., checkmark animation). Subtle animation when adding/removing items from lists.
- **AI Explanations:** Smooth appearance of the explanation modal/panel. Typing animation effect for AI-generated text.
EDGE CASES:
- **Empty States:** Display user-friendly messages and clear calls to action when lists are empty (e.g., 'No projects yet. Click "New Project" to start.', 'No tasks assigned.').
- **Error Handling:** Global error boundary to catch unexpected errors. Specific error messages for API failures, code execution errors, invalid inputs. Use `Toast` notifications for user feedback on errors and successes.
- **Validation:** Client-side validation for all form inputs (required fields, correct formats like dates, email). Server-side validation if a backend is implemented.
- **Accessibility (a11y):** Use semantic HTML. Ensure proper ARIA attributes where necessary. Keyboard navigation support. Sufficient color contrast. Focus management in modals and forms.
- **Code Execution:** Handle timeouts, memory limits, uncaught exceptions. Sanitize inputs to prevent security vulnerabilities.
- **AI Model Failures:** Gracefully handle cases where the AI cannot provide a relevant explanation or suggestion. Provide fallback text like 'AI is currently unavailable or could not process this request.'
SAMPLE DATA:
1. **Project 1 (Initial)**:
```json
{
"id": "proj_main_001",
"title": "Supernova Light Curve Analysis",
"description": "Analyzing Type Ia supernovae light curves to refine cosmological distance measurements.",
"status": "To Do",
"students": ["Alice"],
"createdAt": "2024-01-10T09:00:00Z",
"updatedAt": "2024-01-10T09:00:00Z",
"tasks": [
{"id": "task_main_001", "projectId": "proj_main_001", "title": "Literature Review", "status": "To Do", "dueDate": "2024-01-20"},
{"id": "task_main_002", "projectId": "proj_main_001", "title": "Setup Analysis Environment", "status": "To Do", "dueDate": "2024-01-25"}
],
"pipeline": null,
"codeRuns": []
}
```
2. **Project 2 (In Progress)**:
```json
{
"id": "proj_gal_002",
"title": "Galaxy Clustering Signature",
"description": "Investigating Baryon Acoustic Oscillations (BAO) in simulated dark matter halos.",
"status": "In Progress",
"students": ["Bob"],
"createdAt": "2023-11-15T14:30:00Z",
"updatedAt": "2023-12-20T16:45:00Z",
"tasks": [
{"id": "task_gal_001", "projectId": "proj_gal_002", "title": "Reproduce Simulation Setup", "status": "Completed", "dueDate": "2023-11-30"},
{"id": "task_gal_002", "projectId": "proj_gal_002", "title": "Implement Correlation Function", "status": "In Progress", "dueDate": "2024-01-05"}
],
"pipeline": {
"steps": [
{"name": "Load Simulation Data", "tool": "Astropy FITS", "parameters": {}},
{"name": "Generate Pair Counts", "tool": "Custom Python Script", "parameters": {"max_sep": 100}},
{"name": "Calculate Real Space Correlation Function", "tool": "Numpy", "parameters": {"bin_edges": [0, 1, 2, ..., 100]}}
]
},
"codeRuns": [
{
"id": "run_gal_001",
"projectId": "proj_gal_002",
"codeFile": "//correlation_function.py content...",
"parameters": {"max_sep": 100, "num_bins": 100},
"output": {"plotUrl": "/plots/corr_func_run1.png", "log": "Calculation successful.", "dataFile": "/data/run1_corr.npy"},
"timestamp": "2023-12-18T11:00:00Z"
}
]
}
```
3. **Resource Example**:
```json
{
"id": "res_gal_data_001",
"projectId": "proj_gal_002",
"name": "Simulated Halo Catalog",
"type": "Dataset",
"location": "/datasets/halo_catalog_sim_v2.fits",
"description": "Dark matter halo catalog from N-body simulation run."
}
```
4. **Task Example**:
```json
{
"id": "task_ai_003",
"projectId": "proj_main_001",
"title": "Explain Photometric Redshift Estimation",
"description": "Student needs help understanding the".join(["Bayesian approach used in paper."]),
"status": "In Progress",
"dueDate": "2024-02-01"
}
```
5. **Code Run with Explanation Request**:
```json
{
"id": "run_expl_001",
"projectId": "proj_gal_002",
"codeFile": "// Simple data loading script...",
"parameters": {"data_path": "/datasets/halo_catalog_sim_v2.fits"},
"output": {"log": "Data loaded successfully. Shape: (100000, 12)", "preview": "[[...]]" },
"timestamp": "2023-12-21T09:15:00Z",
"explanationRequestId": "exp_gal_001" // Link to a request for explanation
}
```
DEPLOYMENT NOTES:
- **Build:** Use Vite or Create React App's build command (`npm run build` or `yarn build`). Configure base path if deploying to a subdirectory.
- **Environment Variables:** Use `.env` files for API keys (if any), backend URLs, feature flags. Prefix variables with `VITE_` for Vite or `REACT_APP_` for CRA to be accessible in the frontend build.
- **Hosting:** Static hosting platforms like Vercel, Netlify, or GitHub Pages are suitable for the frontend. Consider a backend service (e.g., Node.js/Express, Python/Flask) with a database (e.g., PostgreSQL) for user accounts, persistent storage, and AI model integration if moving beyond MVP simulation.
- **Performance Optimizations:** Code splitting with React.lazy and Suspense. Image optimization. Efficient state management. Minimize re-renders using `React.memo`. Use `useMemo` and `useCallback` where appropriate. Bundle analysis to identify large dependencies.
- **CORS:** If a separate backend is used, configure CORS headers appropriately on the backend to allow requests from the frontend domain.
- **Mocking:** For the MVP, use mock API endpoints (e.g., with `msw` - Mock Service Worker) or directly manage state within the frontend to simulate data fetching and AI responses.