ASIMOV.Directory

A modern, responsive web application for discovering and exploring modules from the ASIMOV ecosystem. Built with SvelteKit and Tailwind CSS, it provides an intuitive interface to browse GitHub repositories from the asimov-modules organization.

🚀 Features

• Real-time GitHub Integration: Fetches live data from the asimov-modules GitHub organization
• Smart Sorting: Multiple sorting options including relevance, popularity, newest, and recently updated
• Responsive Design: Optimized for desktop, tablet, and mobile devices
• Interactive Module Cards: Display stars, contributors, languages, topics, and last update
• Loading States: Smooth skeleton loading animations
• Rate Limit Handling: Supports both authenticated and unauthenticated GitHub API access
• Custom Theme: Beautiful design using custom color palette

🛠 Tech Stack

• Framework: SvelteKit
• Styling: Tailwind CSS v4
• Icons: Phosphor Svelte
• API: GitHub REST API
• TypeScript: Full type safety
• Deployment: Node.js adapter ready

📋 Prerequisites

• Node.js 22+ (see .nvmrc)
• npm, pnpm, or yarn
• GitHub Personal Access Token (optional but recommended)

🔧 Installation

1. Clone the repository

   git clone https://github.com/your-username/asimov.directory.git
   cd asimov.directory

2. Install dependencies

   nvm use # Ensure you are using Node.js v22 (required for this project's ESM features and performance optimizations)
   
   npm install
   # or
   pnpm install
   # or
   yarn install

3. Start the development server

   npm run dev

   Open http://localhost:5173 in your browser.

Data Source

The application fetches module data from the ASIMOV Platform API

This API provides:

• Module repository information
• GitHub stars and metadata
• YAML manifest data for each module
• Organization statistics

🎨 Customization

Color Theme

The project uses a custom color palette defined in src/app.css:

@theme {
	--color-gGray-100: #f6f6f6;
	--color-sSlate-800: #04163c;
	--color-oOrange-500: #f37021;
	/* ... more colors */
}

Sorting Options

Four sorting methods are available:

• Most Relevant: Custom algorithm combining stars, activity, description, and topics
• Most Popular: Sorted by GitHub stars
• Newest: Recently created repositories
• Recently Updated: Latest activity

Excluded Repositories

Configure which repositories to exclude in src/lib/github.ts:

const EXCLUDED_REPOS = ['.github', 'docs', 'template'];

🚀 Deployment

Build for Production

npm run build

Preview Production Build

npm run preview

Deploy Options

The project is configured with @sveltejs/adapter-node and can be deployed to:

• Vercel: vercel deploy
• Netlify: Connect GitHub repository
• Docker: Use the generated build directory
• VPS: Run node build after building

Environment Variables for Production

No environment variables are required for production deployment since the app uses a public API.

🧪 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build
npm run check        # Run Svelte type checking
npm run lint         # Run ESLint and Prettier
npm run format       # Format code with Prettier

Code Quality

• TypeScript: Full type safety with strict mode
• ESLint: Code linting with Svelte support
• Prettier: Code formatting with Svelte and Tailwind plugins

📊 API Rate Limits

The application monitors GitHub API rate limits:

• Displays remaining requests in console
• Graceful fallback for missing data
• Handles rate limit exceeded errors

🤝 Contributing

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

🔗 Links

• Live Demo: asimov.directory
• ASIMOV Modules: github.com/asimov-modules
• Issues: Report bugs or request features

📞 Support

If you have any questions or need help, please:

1. Check the Issues page
2. Create a new issue with details about your problem
3. Contact the ASIMOV.systems team

---