Code Analysis Dashboard

A comprehensive code analysis dashboard built with React, TypeScript, and Vite for analyzing repository code metrics, findings, and analysis runs.

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Development
• Testing
• Building
• Deployment
• Project Structure
• Contributing
• License

✨ Features

• Repository Dashboard: View and manage code repositories
• Analysis Runs: Track and monitor code analysis executions
• Findings Management: Display and filter code findings by severity
• Real-time Updates: Live data synchronization with Supabase
• Responsive Design: Mobile-friendly interface with modern UI
• Type-Safe: Full TypeScript support with strict type checking
• Testing: Comprehensive unit and integration tests with Vitest

🔧 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: >= 18.0.0 (Download)
• npm: >= 9.0.0 (comes with Node.js)
• Git: For version control

Verify your installations:

node --version    # Should output v18.0.0 or higher
npm --version     # Should output 9.0.0 or higher
git --version     # Should output git version

📦 Installation

1. Clone the Repository

git clone https://github.com/stomde/Adm.git
cd Adm

2. Install Dependencies

npm install

This will install all dependencies listed in package.json.

3. Environment Setup

Create a .env.local file in the root directory by copying the template:

cp .env.example .env.local

Edit .env.local and add your configuration values:

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key_here

# API Configuration
VITE_API_BASE_URL=http://localhost:3000

# Optional: Feature Flags
VITE_ENABLE_DEBUG_MODE=false
VITE_MAX_RETRIES=3

⚠️ Important: Never commit .env.local to version control. It's already in .gitignore.

⚙️ Configuration

TypeScript Configuration

The project uses strict TypeScript settings. Configuration files:

• tsconfig.json - Main TypeScript configuration
• tsconfig.node.json - Configuration for Node.js tools

Key TypeScript settings:

• strict: true - Enables all strict type checking options
• noUnusedLocals: true - Errors on unused local variables
• noUnusedParameters: true - Errors on unused parameters
• noFallthroughCasesInSwitch: true - Ensures switch statements are exhaustive

Code Quality

The project includes pre-configured tools for code quality:

• ESLint (.eslintrc.json) - Static code analysis
• Prettier (.prettierrc) - Code formatting
• EditorConfig (.editorconfig) - Consistent editor settings

🚀 Usage

Development Server

Start the development server with hot module replacement:

npm run dev

The application will be available at http://localhost:5173

View Application

Open your browser and navigate to:

http://localhost:5173

The dashboard will load repositories from your Supabase backend.

💻 Development

Available Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code and fix issues
npm run lint

# Check linting without fixing
npm run lint:check

# Format code with Prettier
npm run format

# Check formatting
npm run format:check

# Type checking
npm run type-check

# Run tests
npm run test

# Run tests with UI
npm run test:ui

# Generate test coverage
npm run test:coverage

Project Structure

Adm/
├── .github/
│   ├── workflows/
│   │   ├── lint.yml          # Linting workflow
│   │   ├── test.yml          # Testing workflow
│   │   └── build.yml         # Build verification workflow
│   └── ISSUE_TEMPLATE/       # GitHub issue templates
├── src/
│   ├── components/           # React components
│   │   ├── AddRepositoryModal.tsx
│   │   ├── AnalysisRunsList.tsx
│   │   ├── FindingsList.tsx
│   │   ├── RepositoryCard.tsx
│   │   └── ErrorBoundary.tsx
│   ├── hooks/                # Custom React hooks
│   │   └── useApi.ts
│   ├── lib/                  # Utility functions
│   │   └── supabase.ts
│   ├── pages/                # Page components
│   │   ├── Dashboard.tsx
│   │   └── RepositoryDetail.tsx
│   ├── types/                # Shared TypeScript types
│   │   └── index.ts
│   ├── App.tsx
│   ├── App.css
│   ├── index.css
│   └── main.tsx
├── .editorconfig             # Editor configuration
├── .env.example              # Environment template
├── .eslintrc.json            # ESLint configuration
├── .gitignore                # Git ignore rules
├── .prettierrc                # Prettier configuration
├── package.json              # Project dependencies
├── tsconfig.json             # TypeScript configuration
├── vite.config.ts            # Vite configuration
└── README.md                 # This file

Creating New Components

When creating new components, follow this structure:

// src/components/MyComponent.tsx
import { FC, ReactNode } from 'react'
import './MyComponent.css'

interface MyComponentProps {
  title: string
  children?: ReactNode
}

const MyComponent: FC<MyComponentProps> = ({ title, children }) => {
  return (
    <div className="my-component">
      <h1>{title}</h1>
      {children}
    </div>
  )
}

export default MyComponent

🧪 Testing

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage

Writing Tests

Tests should be placed alongside their components:

// src/components/MyComponent.test.tsx
import { render, screen } from '@testing-library/react'
import MyComponent from './MyComponent'

describe('MyComponent', () => {
  it('renders with title', () => {
    render(<MyComponent title="Test" />)
    expect(screen.getByText('Test')).toBeInTheDocument()
  })
})

🏗️ Building

Production Build

Create an optimized production build:

npm run build

Output will be generated in the dist/ directory.

Preview Production Build

Preview the production build locally:

npm run preview

Then open http://localhost:4173 in your browser.

🌐 Deployment

Deploy to Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Configure environment variables in Vercel dashboard
3. Deploy with a single click

# Or use Vercel CLI
npm install -g vercel
vercel

Deploy to Netlify

1. Connect your GitHub repository to Netlify
2. Set build command: npm run build
3. Set publish directory: dist
4. Configure environment variables
5. Deploy

Deploy to GitHub Pages

1. Add to vite.config.ts:

export default defineConfig({
  base: '/Adm/',
  // ... rest of config
})

2. Build and deploy

📁 Key Files & Their Purposes

File	Purpose
src/types/index.ts	Shared TypeScript type definitions
.env.example	Environment variable template
.eslintrc.json	ESLint configuration for code quality
.prettierrc	Prettier configuration for code formatting
.gitignore	Git ignore rules
vite.config.ts	Vite build configuration
tsconfig.json	TypeScript configuration

🔍 Code Quality

Pre-commit Hooks

The project uses Husky and lint-staged for pre-commit hooks:

# Install Husky
npm run prepare

# This will automatically:
# - Run ESLint on staged files
# - Run Prettier on staged files
# - Run type checking

Running Code Quality Checks

# Lint check only (no fix)
npm run lint:check

# Format check only (no fix)
npm run format:check

# Type checking
npm run type-check

🐛 Troubleshooting

Issue: Dependencies not installing

Solution:

rm -rf node_modules package-lock.json
npm install

Issue: Port 5173 already in use

Solution:

# Use different port
npm run dev -- --port 3001

Issue: Environment variables not loading

Solution:

• Ensure .env.local exists in the root directory
• Restart the development server
• Verify variables are prefixed with VITE_

Issue: TypeScript errors

Solution:

# Run type checking
npm run type-check

# Clear cache and reinstall
npm run type-check

📚 API Documentation

Supabase Integration

The application connects to Supabase for data management:

// Configuration in src/lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.VITE_SUPABASE_URL!,
  process.env.VITE_SUPABASE_ANON_KEY!
)

export default supabase

Custom Hooks

useApi Hook

const { request, loading, error } = useApi()

// Fetch data
const data = await request('/repositories')

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• Code passes linting: npm run lint:check
• Code is properly formatted: npm run format
• Types are correct: npm run type-check
• Tests pass: npm run test

📋 CI/CD Pipeline

The project includes GitHub Actions workflows for:

• Lint Workflow (.github/workflows/lint.yml)

  • Runs ESLint on all pull requests
  • Ensures code quality standards

• Test Workflow (.github/workflows/test.yml)

  • Runs unit tests on all branches
  • Generates coverage reports

• Build Workflow (.github/workflows/build.yml)

  • Verifies production build succeeds
  • Tests build output

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

stomde - @stomde

📞 Support

For issues, questions, or suggestions:

• Open a GitHub Issue
• Check existing documentation
• Review the contributing guide

🙏 Acknowledgments

• React - UI framework
• Vite - Build tool
• TypeScript - Type safety
• Supabase - Backend services
• Recharts - Data visualization
• Lucide Icons - Icon library

---

Last Updated: 2026-05-17
Version: 0.1.0