PROJECT OVERVIEW:
This project is to build a single-page application (SPA) called 'Kod Düzeni: GitHub Uptime Takipçisi' (Code Order: GitHub Uptime Tracker). The application's primary goal is to provide developers, project managers, and DevOps engineers with clear, historical, and real-time uptime data for their GitHub repositories. It aims to solve the problem of easily accessing and understanding the reliability of GitHub services, which is crucial for project planning, SLA adherence, and overall system stability. The core value proposition is to offer a user-friendly interface that visualizes uptime metrics, allowing users to track the performance of their critical repositories and identify potential issues proactively. This tool will empower users to make informed decisions about their project's infrastructure and service availability.
TECH STACK:
- Frontend Framework: React (using Create React App or Vite for setup)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand or React Context API for managing application state.
- Routing: React Router DOM for handling navigation within the SPA.
- Charting Library: Chart.js or Recharts for visualizing uptime data.
- API Fetching: Axios or native fetch API for interacting with external APIs (if any, or for mock data simulation).
- Local Storage: For persisting user preferences, favorite repositories, and potentially cached data.
- Deployment: Vercel or Netlify for easy deployment and CI/CD integration.
CORE FEATURES:
1. **Repository Search and Add:**
* User Flow: The user lands on the dashboard. They see an input field to search for GitHub repositories (e.g., by owner/repo name). Upon entering a valid repository name and clicking 'Add', the repository is added to their tracked list.
* Details: A search bar is prominently displayed. Autocomplete suggestions can be implemented for popular repositories. Error handling for invalid repository names or private repositories.
2. **Dashboard and Uptime Visualization:**
* User Flow: After adding repositories, the user sees a dashboard listing all tracked repositories. Each repository entry displays its name, owner, and a chart showing its historical uptime percentage over a selected period (e.g., last 7 days, 30 days, 1 year).
* Details: The main view will be the dashboard. Each listed repository will have a dedicated card or row. A line or bar chart will visualize uptime. Users can select different time ranges for the chart. Loading states for chart data.
3. **Detailed Repository View:**
* User Flow: Clicking on a specific repository card on the dashboard navigates the user to a detailed view for that repository.
* Details: This view shows more granular uptime data, including specific outage periods, duration of outages, and the calculated uptime percentage for different periods (daily, weekly, monthly). It might also include direct links to relevant GitHub status pages or issue trackers if available.
4. **Favorite/Pinning Feature:**
* User Flow: Users can 'star' or 'pin' specific repositories on their dashboard to bring them to the top or highlight them.
* Details: A star/pin icon next to each repository entry. Toggled state is saved using local storage.
5. **Basic Alerting (MVP):**
* User Flow: If a repository's uptime drops below a predefined threshold (e.g., 99.5%) within a certain period, a visual indicator (e.g., a warning badge) appears on the dashboard.
* Details: Configurable threshold in settings (future iteration). For MVP, a hardcoded threshold is acceptable. The indicator should be visually distinct.
UI/UX DESIGN:
- **Layout:** Single-page application layout. A persistent navigation bar (sidebar or top bar) for accessing the dashboard, settings, and potentially other features. Main content area displays the selected view (dashboard, repository detail).
- **Color Palette:** A clean, professional, and modern palette. Primary colors could be dark blues or grays for a tech-focused feel. Accent colors (e.g., green for good uptime, orange/red for issues) should be used sparingly for status indicators and calls to action. Use Tailwind CSS's default color scheme as a base and customize.
- **Typography:** Use a readable sans-serif font family (e.g., Inter, Poppins, or default Tailwind fonts). Clear hierarchy using font sizes and weights for headings, subheadings, and body text.
- **Responsive Design:** Mobile-first approach. The layout should adapt seamlessly to various screen sizes (desktops, tablets, mobile phones). Use Tailwind's responsive modifiers (sm:, md:, lg:, xl:) extensively. Ensure charts are responsive and legible on smaller screens.
- **Component Hierarchy:** Dashboard -> RepositoryList -> RepositoryCard -> UptimeChart. Detail View -> UptimeDetails -> OutageList.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing.
- `Header.js`: Top navigation bar or sidebar. Contains logo, app title, navigation links.
- `Dashboard.js`: Main view. Fetches and displays the list of tracked repositories. Manages the list state.
- `RepositoryList.js`: Renders a list of `RepositoryCard` components.
- `RepositoryCard.js`: Displays summary information for a single repository (name, owner, uptime percentage, favorite toggle, link to detail view). Receives repository data as props.
- `UptimeChart.js`: Reusable chart component using a charting library. Receives data and configuration (time range, type) as props.
- `SearchBar.js`: Input component for searching GitHub repositories. Handles input changes and submission.
- `RepositoryDetail.js`: Detailed view for a single repository. Shows granular data and outage history.
- `OutageList.js`: Displays a list of historical outage events for a repository.
- `Settings.js` (Optional for MVP): For future configuration options.
- `LoadingSpinner.js`: Reusable component for indicating loading states.
- `ErrorMessage.js`: Component to display errors to the user.
DATA MODEL:
- **Repository Object:**
```json
{
"id": "unique-repo-id",
"owner": "github_username",
"name": "repository_name",
"isFavorite": false,
"uptimeData": [
// Array of objects, each representing a data point for a specific time
{
"timestamp": "2023-10-27T10:00:00Z",
"uptimePercentage": 99.95,
"status": "operational" // 'operational', 'degraded', 'outage'
}
],
"outages": [
// Array of outage events
{
"startTime": "2023-10-26T08:00:00Z",
"endTime": "2023-10-26T09:30:00Z",
"durationMinutes": 90,
"description": "Brief service disruption"
}
]
}
```
- **Application State:** Will be managed using Zustand or Context API. Includes:
* `trackedRepositories`: Array of Repository Objects.
* `currentUser` (Optional, for future auth).
* `settings`: { `defaultTimeRange`: '30d', `alertThreshold`: 99.5 }.
* `isLoading`: Boolean flag for global loading states.
* `error`: Error message string or object.
- **Local Storage:** `localStorage.setItem('trackedRepos', JSON.stringify(trackedRepositories))` to persist the list between sessions.
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on `RepositoryCard` elements when hovered.
- **Transition Animations:** Smooth transitions for elements appearing/disappearing (e.g., when adding/removing a repository, toggling favorite). Tailwind CSS transitions (`transition-all`, `duration-300`) can be used.
- **Loading States:** Display `LoadingSpinner` components while fetching data for charts or repository lists. Placeholder UI elements can be shown before data is fully loaded.
- **Micro-interactions:** Visual feedback when adding/removing a repository (e.g., a brief confirmation message or animation). Star/unstar animation.
EDGE CASES:
- **Empty State:** When no repositories are tracked, display a clear message encouraging the user to search and add repositories, potentially with a prominent search bar.
- **Error Handling:** Display user-friendly error messages for:
* Invalid repository name input.
* Network errors during data fetching.
* API rate limiting (if using real GitHub API).
* Private repository access denied.
- **Validation:** Input validation for the search bar (e.g., preventing empty submissions).
- **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes where necessary. Keyboard navigation support. Sufficient color contrast. Alt text for meaningful images/icons.
- **Data Inconsistencies:** Handle cases where uptime data might be missing or incomplete for certain periods.
SAMPLE DATA:
1. **Repository Card Data (for Dashboard):**
```json
[
{
"id": "react-router-reactrouter",
"owner": "remix-run",
"name": "react-router",
"isFavorite": true,
"currentUptimePercentage": 99.98 // Simplified for card view
},
{
"id": "vuejs-vuejs",
"owner": "vuejs",
"name": "vue",
"isFavorite": false,
"currentUptimePercentage": 99.90
}
]
```
2. **Detailed Uptime Data (for `UptimeChart` and `RepositoryDetail`):
```json
{
"id": "remix-run-react-router",
"owner": "remix-run",
"name": "react-router",
"uptimeData": [
{"timestamp": "2023-10-20T00:00:00Z", "uptimePercentage": 99.99, "status": "operational"},
{"timestamp": "2023-10-21T00:00:00Z", "uptimePercentage": 100.00, "status": "operational"},
{"timestamp": "2023-10-22T00:00:00Z", "uptimePercentage": 99.95, "status": "operational"},
{"timestamp": "2023-10-23T00:00:00Z", "uptimePercentage": 99.80, "status": "degraded"},
{"timestamp": "2023-10-24T00:00:00Z", "uptimePercentage": 99.90, "status": "operational"}
],
"outages": [
{
"startTime": "2023-10-23T14:00:00Z",
"endTime": "2023-10-23T16:30:00Z",
"durationMinutes": 150,
"description": "Intermittent performance issues"
}
]
}
```
3. **Mock User Settings:**
```json
{
"defaultTimeRange": "30d",
"alertThreshold": 99.5
}
```
DEPLOYMENT NOTES:
- **Build Process:** Use the standard build command for your chosen React setup (e.g., `npm run build` or `yarn build`). Ensure environment variables are correctly configured for the build process.
- **Environment Variables:** Store API keys (if any), backend service URLs, etc., in environment variables (e.g., `.env` files). Prefixing with `REACT_APP_` or `VITE_` is common.
- **Performance Optimizations:** Code splitting using React.lazy and Suspense for route-based splitting. Image optimization if applicable. Memoization (React.memo, useMemo, useCallback) to prevent unnecessary re-renders. Bundle analysis to identify large dependencies.
- **HTTPS:** Ensure the deployed application uses HTTPS.
- **CORS:** If interacting with a backend API, ensure proper CORS configuration on the server.
- **SEO (Basic):** Implement basic meta tags and potentially a sitemap for better discoverability, although it's an SPA.
- **Favicon:** Include a favicon for the application.
- **Error Boundaries:** Implement React Error Boundaries to catch JavaScript errors in components and display a fallback UI.
- **Service Workers:** Consider adding a Service Worker for potential offline capabilities or faster loading on repeat visits (PWA features).