You are an AI assistant tasked with building a Single Page Application (SPA) called 'Bilim Mirası: Tarihi Notlar Analizi' (Legacy of Science: Historical Notes Analysis). This application aims to digitize, analyze, and provide context for historical handwritten scientific notes, starting with Galileo. The primary goal is to make historical scientific discoveries and thought processes more accessible and understandable through AI-powered text analysis and contextual information.
PROJECT OVERVIEW:
'Bilim Mirası' addresses the challenge of accessing and interpreting historical scientific documents, which are often in handwritten form, difficult to read, and lack immediate context. By leveraging OCR and AI, the platform will digitize these notes, extract key information, identify themes, and provide users with a richer understanding of the historical scientific landscape. The core value proposition is to unlock the knowledge hidden within historical texts, making them accessible to a modern audience of researchers, students, and enthusiasts.
TECH STACK:
- Frontend Framework: React (using Vite for fast development)
- Styling: Tailwind CSS for utility-first styling and rapid UI development.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for handling navigation within the SPA.
- OCR Library: Tesseract.js for performing Optical Character Recognition on uploaded images of handwritten notes.
- Text Analysis: Natural Language Processing (NLP) libraries (e.g.,compromise.js for client-side NLP tasks, or an integration with a server-side NLP API if complexity demands).
- Data Fetching/API: `fetch` API for interacting with potential backend services (if any are added later).
- Deployment: Vercel or Netlify for seamless deployment.
CORE FEATURES:
1. **Document Upload & Digitization:**
* User Flow: Users can upload images (JPG, PNG, PDF) of historical documents. The application will process these images using Tesseract.js to perform OCR and extract text. A loading state will be displayed during processing. Successful extraction leads to the display of the digitized text.
* Details: Support for multiple image uploads. Progress indicator for OCR. Display of extracted text in a dedicated editor pane.
2. **AI-Powered Text Analysis:**
* User Flow: Once text is digitized or entered, users can trigger analysis. The application will apply NLP techniques to identify keywords, key phrases, topics, and potentially sentiment (if applicable to the historical context). Results are displayed in a structured manner.
* Details: Keyword extraction (top N keywords). Topic modeling (clustering text into themes). Optional sentiment analysis (requires careful contextualization for historical texts).
3. **Historical Contextualization:**
* User Flow: The platform will automatically link extracted keywords and topics to a database of historical figures, events, scientific concepts, and timelines. Users can browse related information via interactive cards or a timeline view.
* Details: Database of pre-defined entities (Galileo, telescope, heliocentrism, scientific revolution, etc.). Linking mechanisms to display relevant biographical information, event summaries, and concept definitions.
4. **User Note Management:**
* User Flow: Registered users can save their digitized notes, analysis results, and related context links to their personal dashboard. They can organize notes into projects or collections.
* Details: User authentication (simple email/password or OAuth). Personal dashboard displaying saved notes. Ability to tag or categorize saved items.
UI/UX DESIGN:
- **Layout:** A clean, single-page layout with a sidebar for navigation (Upload, Analysis, Dashboard) and a main content area. The main area will dynamically display components based on user actions (e.g., document viewer, analysis results, context cards).
- **Color Palette:** Primarily muted, scholarly tones: off-white backgrounds (`#F8F8F8`), dark grays for text (`#333333`), a primary accent color like a deep blue (`#003366`) or sepia (`#704214`) for interactive elements and highlights. Secondary accents for alerts or specific data types.
- **Typography:** Use a serif font (e.g., 'Merriweather' or 'Lora') for headings and main text to evoke a historical feel, and a clean sans-serif font (e.g., 'Inter' or 'Roboto') for UI elements, labels, and code/data display.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Main content reflows gracefully. Ensure readability and usability across all device sizes.
- **Components:** Clear visual hierarchy. Consistent spacing and alignment using Tailwind CSS's spacing scale. Interactive elements should have clear hover and focus states.
DATA MODEL:
- **Note Object:**
```json
{
"id": "string",
"title": "string",
"originalFileName": "string",
"uploadedAt": "Date",
"digitizedText": "string",
"analysisResults": {
"keywords": ["string"],
"topics": [{"topic": "string", "confidence": "number"}],
"sentiment": "string" // e.g., 'neutral', 'positive', 'negative' - requires careful historical interpretation
},
"relatedContext": ["string"] // IDs linking to context entities
}
```
- **Context Entity Object:**
```json
{
"id": "string",
"name": "string",
"type": "string", // e.g., 'person', 'event', 'concept', 'discovery'
"description": "string",
"imageUrl": "string",
"relatedIds": ["string"] // Links to other context entities
}
```
- **State Management (Zustand):**
* `useStore` hook managing:
* `notes`: Array of `Note Object`.
* `currentNote`: The currently viewed/edited `Note Object`.
* `contextEntities`: Array of `Context Entity Object`.
* `isLoading`: Boolean for global loading states.
* `error`: String for error messages.
* `isAuthenticated`: Boolean for auth state.
* `userProfile`: User details.
* Actions for fetching, uploading, analyzing, saving notes, and managing context data.
- **Local Storage:** Use for persisting user preferences or temporarily storing unsaved drafts. `Note` objects will be stored primarily in the application state, potentially synced to a backend later.
COMPONENT BREAKDOWN:
- **`App.jsx`:** Main application component, sets up routing and global layout.
- **`Header.jsx`:** Top navigation bar, logo, user authentication status.
- **`Sidebar.jsx`:** Navigation menu (Upload, Analysis, Dashboard, Settings).
- **`UploadPage.jsx`:** Contains the `DocumentUploader` component.
- **`DocumentUploader.jsx`:** Handles file input, displays upload progress, triggers OCR.
- **`EditorPane.jsx`:** Displays and allows editing of digitized text.
- **`AnalysisPanel.jsx`:** Contains `KeywordExtractor`, `TopicModeler`, `SentimentAnalyzer` components. Triggers analysis.
- **`KeywordExtractor.jsx`:** Displays extracted keywords.
- **`TopicModeler.jsx`:** Displays identified topics and their relevance.
- **`ContextViewer.jsx`:** Displays historical context cards or timeline based on selected text/topics.
- **`ContextCard.jsx`:** Individual display for a historical entity (person, event, concept).
- **`DashboardPage.jsx`:** Displays a list of saved user notes.
- **`NoteListItem.jsx`:** Individual item in the dashboard list.
- **`LoadingSpinner.jsx`:** Reusable loading indicator.
- **`ErrorMessage.jsx`:** Displays error messages.
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/fade-out animations between major sections using `Framer Motion` or CSS transitions.
- **Button Hovers:** Slight scale-up or background color change on interactive elements.
- **OCR/Analysis Loading:** Use `LoadingSpinner` with progress indicators where appropriate (e.g., upload progress bar, pulsing animation during analysis).
- **Context Card Expansion:** Smooth expand/collapse animation for detailed views of context information.
- **Micro-interactions:** Subtle visual feedback on successful save actions or form submissions.
EDGE CASES:
- **Empty State:** Display user-friendly messages and clear calls to action when there are no notes, no analysis results, or no related context (e.g., "Upload your first document to begin.").
- **Error Handling:** Graceful handling of OCR failures, network errors, invalid file uploads. Display clear, actionable error messages using `ErrorMessage` component.
- **Validation:** Client-side validation for file types and sizes during upload. Ensure text input fields are handled appropriately.
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure proper ARIA attributes for interactive components. Keyboard navigability for all features. Sufficient color contrast.
- **Large Text Files:** Implement efficient rendering for very long digitized texts (virtual scrolling if necessary). Handle potential performance issues with large-scale NLP processing (consider client-side vs. server-side trade-offs).
SAMPLE DATA:
1. **Note 1 (Galileo's observations):**
```json
{
"id": "note-galileo-001",
"title": "Jupiter's Moons Observations",
"originalFileName": "galileo_jupiter_notes.png",
"uploadedAt": "2023-10-27T10:00:00Z",
"digitizedText": "Observed four small stars near Jupiter, two east, two west. They appear fixed to Jupiter... Could these be moons? Further observation required. The date was Jan 7, 1610.",
"analysisResults": {
"keywords": ["Jupiter", "stars", "moons", "observation", "January 7, 1610"],
"topics": [{"topic": "Astronomy", "confidence": 0.9}, {"topic": "Observational Data", "confidence": 0.85}],
"sentiment": "curious"
},
"relatedContext": ["entity-jupiter", "entity-galileo", "entity-discovery-moons", "event-1610"]
}
```
2. **Context Entity (Galileo):**
```json
{
"id": "entity-galileo",
"name": "Galileo Galilei",
"type": "person",
"description": "An influential Italian astronomer, physicist, and engineer, often called the 'father of observational astronomy'. His work laid the foundation for modern physics and astronomy.",
"imageUrl": "/images/galileo.jpg",
"relatedIds": ["entity-jupiter", "entity-heliocentrism", "discovery-moons", "event-scientific-revolution"]
}
```
3. **Context Entity (Jupiter):**
```json
{
"id": "entity-jupiter",
"name": "Jupiter",
"type": "celestial_body",
"description": "The fifth planet from the Sun and the largest in the Solar System. Galileo's observations of its moons were crucial evidence supporting the heliocentric model.",
"imageUrl": "/images/jupiter.jpg",
"relatedIds": ["entity-galileo", "entity-heliocentrism", "discovery-moons"]
}
```
4. **Note 2 (Hypothetical - Newton):**
```json
{
"id": "note-newton-002",
"title": "On Gravity and Falling Objects",
"originalFileName": "newton_gravity_notes.jpg",
"uploadedAt": "2023-10-27T11:00:00Z",
"digitizedText": "The force pulling an apple to the ground appears the same as the force that keeps the Moon in orbit. This suggests a universal law of gravitation.",
"analysisResults": {
"keywords": ["gravity", "apple", "moon", "orbit", "universal law"],
"topics": [{"topic": "Physics", "confidence": 0.95}, {"topic": "Gravitation", "confidence": 0.9}],
"sentiment": "analytical"
},
"relatedContext": ["entity-newton", "concept-gravity", "event-publication-principia"]
}
```
5. **Context Entity (Gravity):**
```json
{
"id": "concept-gravity",
"name": "Universal Gravitation",
"type": "concept",
"description": "Newton's law of universal gravitation states that every point mass attracts every other point mass in the universe with a force that is directly proportional to the product of their masses and inversely proportional to the square of the distance between their centers.",
"imageUrl": "/images/gravity.jpg",
"relatedIds": ["entity-newton", "entity-earth", "entity-sun"]
}
```
DEPLOYMENT NOTES:
- **Build:** Configure Vite for production build (`vite build`). Ensure environment variables are correctly injected.
- **Environment Variables:** Use `.env` files for API keys (if any external services are used), application configuration. Prefix variables with `VITE_` for Vite compatibility.
- **Performance:** Code splitting using React.lazy and Suspense for efficient loading of components. Optimize image assets. Lazy load context data where possible. Ensure Tesseract.js is loaded efficiently, possibly dynamically.
- **HTTPS:** Deploy using a service that provides automatic HTTPS.
- **CORS:** If a separate backend API is used, configure CORS headers appropriately.