As an expert AI software architect and senior full-stack developer, your task is to generate a complete, single-page, responsive React SPA application based on the provided concept. The application, named 'Code Quality Compass', aims to combat the 'vibe coding' phenomenon by analyzing codebases for duplication, potential issues, and lack of underlying structure. It will provide actionable insights and recommendations to improve code quality and maintainability.
## 1. PROJECT OVERVIEW
**Application Name:** Code Quality Compass
**Concept:** A SaaS platform leveraging AI to analyze code repositories, specifically identifying and flagging 'vibe coding' tendencies. 'Vibe coding' is defined as a development practice where developers prioritize superficial implementation over understanding or improving the underlying code structure, leading to technical debt, bugs, and maintainability issues. Code Quality Compass acts as a guide, highlighting duplicated code, architectural weaknesses, and areas lacking robust implementation. It aims to foster a culture of quality and thoroughness in software development.
**Value Proposition:** Empower development teams to write cleaner, more robust, and maintainable code by proactively identifying and rectifying the pitfalls of 'vibe coding'. Improve developer productivity by reducing time spent on debugging issues caused by poor code quality and technical debt. Enhance overall software reliability and reduce long-term maintenance costs.
## 2. TECH STACK
* **Frontend Framework:** React (using Vite for a fast development experience)
* **Styling:** Tailwind CSS (for rapid, utility-first styling)
* **State Management:** Zustand (lightweight, efficient global state management)
* **Routing:** React Router DOM (for client-side routing)
* **API Communication:** Axios (for making HTTP requests)
* **UI Components:** Custom components built with Tailwind CSS, potentially using a small library like Headless UI for accessibility-enhanced components.
* **Icons:** Heroicons
## 3. CORE FEATURES & USER FLOW
**A. Repository Connection:**
* **User Flow:** User lands on the dashboard. Clicks 'Connect Repository'. Selects a Git provider (GitHub initially). Authenticates via OAuth. Chooses a repository from their list. Clicks 'Analyze'.
* **Details:** The application will integrate with GitHub's API (and potentially GitLab/Bitbucket later) to fetch repository details and allow users to select repositories for analysis. Authentication will be handled securely via OAuth.
**B. Code Analysis Dashboard:**
* **User Flow:** After analysis, the user is redirected to the dashboard. The dashboard displays an overview of the analysis results: overall quality score, percentage of duplicated code, detected 'vibe coding' indicators, and recent activity.
* **Details:** This serves as the central hub for all analysis results. It provides a high-level summary and quick links to detailed sections.
**C. Detailed Analysis Reports:**
* **1. Duplication Report:**
* **User Flow:** From the dashboard, clicks 'View Duplication Report'. Sees a list of duplicated code blocks, their locations (file paths, line numbers), and the percentage of code duplication.
* **Details:** Implements a simple algorithm (or integrates with a library) to detect similar code blocks. Displays code snippets and allows users to navigate to the specific files.
* **2. Vibe Coding Indicators Report:**
* **User Flow:** Clicks 'View Vibe Coding Indicators'. Sees a categorized list of potential 'vibe coding' issues (e.g., 'Lack of Comments', 'Shallow Functionality', 'High Complexity', 'No Unit Tests Detected'). Each indicator shows the affected files and line numbers.
* **Details:** This section uses heuristics and patterns to flag code that suggests a lack of deep understanding or effort in underlying implementation. Examples: functions with excessive lines, lack of JSDoc comments, high cyclomatic complexity, missing test files in key areas.
* **3. Architectural Weakness Report:**
* **User Flow:** Clicks 'View Architectural Weaknesses'. Reviews identified issues such as high coupling between modules, low cohesion within modules, or potential performance bottlenecks.
* **Details:** This will be a more advanced feature, possibly using static analysis tools or more sophisticated AI models in future iterations. For MVP, it might focus on basic metrics like module dependencies.
**D. Recommendations & Action Items:**
* **User Flow:** Within each report section, specific recommendations are provided for each identified issue. Users can mark recommendations as 'Acknowledged' or 'Implemented'.
* **Details:** Generates actionable advice. For duplication: 'Refactor this block into a reusable function'. For lack of comments: 'Add JSDoc comments explaining the purpose and parameters'.
## 4. UI/UX DESIGN
* **Layout:** Single Page Application (SPA) with a persistent sidebar navigation (collapsed on small screens) and a main content area. Header includes app logo, user profile/logout, and potentially global actions.
* **Color Palette:** Primary: Deep Blue (#1a202c - dark charcoal), Secondary: Teal (#008080 - a vibrant accent), Accent: Light Gray (#e2e8f0), Text: White (#ffffff) and Light Gray. Use subtle gradients for backgrounds or buttons.
* **Typography:** A clean, modern sans-serif font like Inter or Poppins for readability. Use varying weights and sizes for hierarchy (e.g., H1 for page titles, H2 for section titles, body text for descriptions).
* **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows gracefully. Use Tailwind's responsive prefixes (sm:, md:, lg:) extensively.
* **Key Components:** Dashboard Cards, Code Snippet Viewer, File Tree Navigator, Report Tables, Action Buttons, Loading Spinners, Authentication Forms.
## 5. COMPONENT BREAKDOWN
* **`App.jsx`:** Main application component, sets up routing and global layout.
* **`Layout.jsx`:** Main layout component with sidebar and header.
* **`Sidebar.jsx`:** Navigation menu component.
* Props: `routes` (array of route objects).
* **`Header.jsx`:** Top navigation bar.
* Props: `user` (user object).
* **`Dashboard.jsx`:** Main dashboard view.
* Components: `RepoConnectionForm`, `AnalysisOverviewCard` (multiple).
* **`RepoConnectionForm.jsx`:** Form for connecting GitHub repository.
* Props: `onRepoSelect` (callback function).
* **`AnalysisOverviewCard.jsx`:** Displays a summary metric (e.g., Quality Score, Duplication %).
* Props: `title`, `value`, `icon`, `trend`.
* **`ReportPage.jsx`:** Generic page structure for detailed reports.
* Props: `title`, `children`.
* **`DuplicationReport.jsx`:** Displays the duplication analysis.
* Components: `CodeBlockList`, `CodeSnippetViewer`.
* Props: `duplicates` (array of duplication objects).
* **`VibeCodingReport.jsx`:** Displays vibe coding indicators.
* Components: `IndicatorList`, `FileLocation`.
* Props: `indicators` (array of indicator objects).
* **`ArchitecturalReport.jsx`:** Displays architectural weaknesses.
* Props: `weaknesses` (array of weakness objects).
* **`CodeBlockList.jsx`:** Renders a list of duplicated code blocks.
* Props: `codeBlocks`.
* **`CodeSnippetViewer.jsx`:** Displays a single code snippet with file/line info.
* Props: `code`, `filePath`, `startLine`, `endLine`, `onNavigate`.
* **`IndicatorList.jsx`:** Renders a list of vibe coding indicators.
* Props: `indicators`.
* **`FileLocation.jsx`:** Displays file path and line numbers.
* Props: `filePath`, `startLine`, `endLine`.
* **`Recommendation.jsx`:** Displays a single recommendation.
* Props: `recommendation`, `status`, `onStatusChange`.
* **`LoadingSpinner.jsx`:** Reusable loading indicator.
* **`AuthButton.jsx`:** Button for GitHub OAuth.
## 6. DATA MODEL (Zustand State)
```javascript
// store/analysisStore.js
import create from 'zustand';
const useAnalysisStore = create((set) => ({
repository: null,
analysisResults: null,
isLoading: false,
error: null,
setRepository: (repo) => set({ repository: repo }),
setAnalysisResults: (results) => set({ analysisResults: results }),
setIsLoading: (loading) => set({ isLoading: loading }),
setError: (err) => set({ error: err }),
}));
export default useAnalysisStore;
// Example analysisResults structure:
/*
{
qualityScore: 8.2,
duplication: {
percentage: 15.5,
blocks: [
{
id: 'dup1',
codeSnippet: 'function calculateTotal(items) { ... }',
filePath: 'src/utils/helpers.js',
startLine: 25,
endLine: 40,
duplicates: [
{ filePath: 'src/components/Cart.jsx', startLine: 110, endLine: 125 },
{ filePath: 'src/services/order.js', startLine: 55, endLine: 70 }
]
}
]
},
vibeIndicators: {
indicators: [
{
type: 'Lack of Comments',
severity: 'medium',
files: [
{ filePath: 'src/api/client.js', startLine: 15, endLine: 60, description: 'Function lacks JSDoc comments explaining parameters and return value.' },
{ filePath: 'src/utils/formatter.js', startLine: 5, endLine: 20, description: 'Method needs clear explanation.' }
]
},
{
type: 'High Complexity',
severity: 'high',
files: [
{ filePath: 'src/services/process.js', startLine: 10, endLine: 150, description: 'Function exceeds recommended cyclomatic complexity threshold.' }
]
}
]
},
architecturalWeaknesses: {
weaknesses: [
{
type: 'High Coupling',
description: 'Module X has too many dependencies on Module Y.',
files: ['src/moduleX.js', 'src/moduleY.js']
}
]
},
recommendations: [
{ id: 'rec1', issueId: 'dup1', text: 'Refactor duplicated code block in helpers.js and Cart.jsx into a shared utility function.', status: 'pending' },
{ id: 'rec2', issueId: 'api/client.js', text: 'Add JSDoc comments to the fetchUsers function in api/client.js.', status: 'pending' }
]
}
*/
// Mock Data Example (for initial state or testing)
const mockAnalysisResults = {
qualityScore: 7.5,
duplication: {
percentage: 12.1,
blocks: [
{
id: 'dup_auth_001',
codeSnippet: 'const user = await db.users.find({ email }); if (!user) { throw new Error(\'User not found\'); }',
filePath: 'src/services/auth.js',
startLine: 30,
endLine: 33,
duplicates: [
{ filePath: 'src/controllers/userController.js', startLine: 50, endLine: 53 },
{ filePath: 'src/routes/profile.js', startLine: 75, endLine: 78 }
]
}
]
},
vibeIndicators: {
indicators: [
{
type: 'Magic Numbers',
severity: 'low',
files: [
{ filePath: 'src/config/constants.js', startLine: 10, endLine: 10, description: 'Directly using number 86400 without explanation.' }
]
},
{
type: 'Long Method',
severity: 'medium',
files: [
{ filePath: 'src/processors/dataProcessor.js', startLine: 1, endLine: 200, description: 'Method exceeds 150 lines, consider breaking it down.' }
]
}
]
},
architecturalWeaknesses: {
weaknesses: []
},
recommendations: [
{ id: 'rec_auth_001', issueId: 'dup_auth_001', text: 'Create a reusable function `findUserByEmail` in a shared utility module.', status: 'pending' },
{ id: 'rec_const_001', issueId: 'src/config/constants.js', text: 'Define constants for magic numbers like 86400 with meaningful names (e.g., SECONDS_IN_DAY).', status: 'pending' }
]
};
// You would use this store in your components like:
// import useAnalysisStore from './store/analysisStore';
// const { analysisResults, isLoading, error } = useAnalysisStore();
```
## 7. ANIMATIONS & INTERACTIONS
* **Page Transitions:** Subtle fade-in/fade-out transitions between pages using `Framer Motion` or simple CSS transitions on route changes.
* **Button Hovers:** Slight scale-up or background color change on button hover states.
* **Loading States:** Use `react-tsparticles` or a simple CSS spinner component (`LoadingSpinner.jsx`) with a translucent overlay when data is being fetched or analyzed. Provide clear feedback that the operation is in progress.
* **Data Table Interactions:** Hover effects on table rows to highlight them. Subtle animations when expanding sections or viewing code snippets.
* **Micro-interactions:** Add small visual cues for actions like marking a recommendation as complete (e.g., a checkmark animation).
## 8. EDGE CASES
* **No Repository Selected:** Display a clear message and prompt the user to connect a repository.
* **Analysis Failure:** Show an informative error message (e.g., 'Analysis failed. Please check repository permissions or try again later.') and log the error details.
* **Empty Repository:** Handle cases where a repository has no code or is empty.
* **Large Repositories:** Implement pagination for long lists of code blocks or indicators. Consider asynchronous processing or background jobs for very large repositories (may require backend infrastructure not covered in this SPA prompt).
* **Authentication Errors:** Gracefully handle OAuth token expiration or invalid permissions.
* **No Results:** If an analysis yields no significant issues, display a positive message like 'Your code quality is excellent!' or 'No major vibe coding indicators found.'
* **Accessibility (a11y):** Ensure all interactive elements have proper ARIA attributes. Use semantic HTML. Ensure sufficient color contrast. Keyboard navigability for all components.
* **Validation:** Client-side validation for any input forms (e.g., repository URL if manual input is added later).
## 9. SAMPLE DATA (Beyond Data Model)
**Sample Repository Data (for `repository` state):**
```json
{
"id": "repo_123",
"name": "awesome-project",
"owner": "your-username",
"url": "https://github.com/your-username/awesome-project",
"provider": "github"
}
```
**More `Vibe Coding Indicators` Examples:**
```json
[
{
"type": "Deeply Nested Logic",
"severity": "medium",
"files": [
{ "filePath": "src/utils/logic.js", "startLine": 10, "endLine": 50, "description": "Excessive nesting (if/else, loops) makes the code hard to follow." }
]
},
{
"type": "Lack of Error Handling",
"severity": "high",
"files": [
{ "filePath": "src/network/api.js", "startLine": 15, "endLine": 30, "description": "Network requests are not wrapped in try/catch blocks." }
]
}
]
```
**More `Recommendations` Examples:**
```json
[
{ "id": "rec_nested_001", "issueId": "src/utils/logic.js", "text": "Refactor nested logic in src/utils/logic.js using guard clauses or helper functions.", "status": "pending" },
{ "id": "rec_api_001", "issueId": "src/network/api.js", "text": "Implement robust error handling (try/catch) for all API calls in src/network/api.js.", "status": "pending" },
{ "id": "rec_long_method_001", "issueId": "src/processors/dataProcessor.js", "text": "Break down the long method in dataProcessor.js into smaller, single-responsibility functions.", "status": "acknowledged" }
]
```
## 10. DEPLOYMENT NOTES
* **Build Tool:** Vite (`npm run build` or `yarn build`). Generates optimized static assets in a `dist` folder.
* **Environment Variables:** Use `.env` files for configuration (e.g., `VITE_GITHUB_CLIENT_ID`, `VITE_API_BASE_URL`). Ensure sensitive keys are handled server-side if this were a full-stack app, but for a SPA, client-side variables like Client ID are acceptable but should be treated with care.
* **Hosting:** Deploy the static build output to platforms like Vercel, Netlify, or GitHub Pages.
* **Performance:** Leverage Vite's optimizations (code splitting, tree shaking). Optimize images. Lazy load components where appropriate. Minimize re-renders by using `React.memo` or `useCallback` judiciously. Ensure efficient state management.
* **CI/CD:** Set up a basic pipeline (e.g., using GitHub Actions) to automatically build and deploy the application on code pushes to the main branch.
* **HTTPS:** Always use HTTPS for deployment, especially when handling authentication tokens.