CodeStash

A collaborative code snippet storage and sharing platform for organizations.

Built for the Digital Innovation Center, University of the Philippines Los Baños.

---

About

CodeStash is a private, organization-scoped code snippet manager where team members can save, tag, search, and share reusable code snippets. It eliminates repeated work by making reusable code discoverable through fuzzy search, tag filtering, and AI-powered semantic search.

Key Features

• Snippet Management — Create, edit, fork, version, and organize code snippets with syntax highlighting for 50+ languages
• Smart Search — Fuzzy full-text search (Meilisearch) + semantic/intent search (OpenAI embeddings) with hybrid ranking
• Tagging System — Organization-wide shared tag library with autocomplete, filtering, and color coding
• Collections — Group snippets into nested folders (up to 3 levels), private or shared
• User Profiles — Public feed showcasing a user's accessible snippets alongside personal account settings (secure password changing, etc.)
• Collaboration — Threaded comments with @mentions, starring, pinning, forking, and activity feeds
• Organization Invitations — Secure email invitation workflow for non-whitelisted domain users (admin-managed)
• Notifications — In-app and email notifications for mentions and comments
• Admin Panel — Full Filament-powered admin with user management, tag moderation, analytics, and audit logs
• REST API — Token-based API (Sanctum) for VS Code extension and CLI tool integration
• Dark Mode — Full dark mode support with a custom brand-aligned color palette

---

Tech Stack

---

Requirements

• PHP 8.4+
• Composer 2.x
• Node.js 20+ & npm 10+
• MySQL 8.4+
• Redis 7.x
• Meilisearch 1.35+ (for search features)
• OpenAI API key (for semantic search)

---

Installation & Setup

1. Fork the Repository

To contribute or deploy your own instance, first fork this repository to your own GitHub account.

1. Click the "Fork" button at the top right of this repository.
2. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/CodeStash.git
cd CodeStash

2. Install Dependencies

You'll need PHP 8.4+, Node.js 20+, and Composer.

composer install
npm install

3. Background Services (macOS / Homebrew)

CodeStash relies on Meilisearch for ultra-fast fuzzy search, Mailpit for testing local emails without complex SMTP credentials, and Redis for caching and background queues.

For macOS users using Homebrew, install and run them with:

# Install Redis, Meilisearch, and Mailpit
brew install redis meilisearch mailpit

# Start all three services in the background using Homebrew Services
brew services start redis
brew services start meilisearch
brew services start mailpit

4. Environment Setup

Copy the example environment file:

cp .env.example .env
php artisan key:generate

Important .env configurations:

1. Database (DB_*): Create a local MySQL database named CodeStash. Leave DB_PASSWORD blank if using default local settings.
2. Mail (MAIL_*): Ensure your mailer is set up to point to your new local Mailpit instance.

   MAIL_MAILER=smtp
   MAIL_HOST=127.0.0.1
   MAIL_PORT=1025
   

   You can view all generated local emails (like user verification) by navigating your browser to http://localhost:8025.
3. Queue (QUEUE_CONNECTION): Set to database or redis. (We use background workers to index search results and calculate stats).
4. Meilisearch (MEILISEARCH_*): Default port is 7700. No master key is required for local dev out of the box.
5. OpenAI (OPENAI_API_KEY): Go to the OpenAI Platform and generate a new secret API key to enable Semantic and Hybrid Search features.

5. Database Setup & Seeding

This will create the necessary tables and seed demo data (roles, users, and snippets):

php artisan migrate:fresh --seed

6. Search Indexing

Once Meilisearch is running and the database is migrated/seeded, you must push the snippets into the search engine:

php artisan scout:import "App\Models\Snippet"

7. Build Frontend Assets

Compile Tailwind CSS and Vite assets:

npm run build

---

Development

Start all primary development services simultaneously with a single command:

composer dev

This runs concurrently:

• Laravel CLI server
• Queue worker (processes jobs like embeddings and stats)
• Log watcher
• Vite dev server (HMR for Tailwind/JS)

Individual Commands Reference

---

🛠️ Code Quality & Tooling

CodeStash includes a strict, automated toolchain to maintain high code quality standards. We use a combination of Composer scripts and npm scripts to check formatting, perform static analysis, run tests, and validate frontend builds.

Composer Scripts

You can run these custom commands directly via Composer. It is recommended to run composer check before submitting any pull requests.

Frontend Compilation

Note on Recent Tooling Workarounds & Fixes

During the implementation of Larastan (Level 5), we addressed several strict-typing requirements:

1. Model Typing: Added comprehensive @property docblocks to Eloquent models (Snippet, User, SnippetComment, SnippetVersion) so PHPStan understands dynamic attributes and relationships without needing inline type-casts.
2. Collection Optimization: Fixed noUnnecessaryCollectionCall warnings in TagService by replacing in-memory collection diff() operations with database-level whereNotIn() queries.
3. Paginator Contracts: Refactored SearchService to use ->items() instead of the concrete ->getCollection() to strictly adhere to the LengthAwarePaginator interface.
4. False Positives (IDE): You may see warnings in your IDE regarding @variant in app.css (Tailwind v4 syntax) or stdClass::delete() calls. These are false positives from the internal IDE parser, not the actual toolchain. The composer analyse command is the single source of truth.
5. Meilisearch Resilience: We implemented global exception handling for CommunicationException and database transactions across all snippet mutation methods. This prevents application crashes and database-search desynchronization if the Meilisearch service is unreachable or times out.
6. Dynamic Language Management: Removed hardcoded language lists. Admins can now manage supported programming languages directly from the Filament Admin Panel (Settings > Languages). We've included over 70+ presets including Mermaid, Markdown, Blade, Solidity, and many more. Only active languages appear in snippet forms and search filters.
7. Admin Navigation: Added a "Back to App" button in the admin sidebar for quick access to the main user dashboard.

---

📂 Project Structure

CodeStash/
├── app/
│   ├── Filament/          # Filament admin resources & widgets
│   ├── Http/
│   │   ├── Controllers/   # Web & API controllers
│   │   ├── Middleware/     # Custom middleware (org scoping)
│   │   └── Requests/      # Form request validation
│   ├── Jobs/              # Queued jobs (embeddings, notifications, indexing)
│   ├── Livewire/          # Livewire components (search, editor, comments)
│   ├── Models/            # Eloquent models
│   ├── Notifications/     # Notification classes
│   ├── Policies/          # Authorization policies
│   └── Services/          # Business logic services
├── database/
│   ├── migrations/        # Database migrations
│   └── seeders/           # Database seeders
├── docs/
│   ├── project_overview.md  # Full project specification
│   └── checklist.md         # Implementation progress tracker
├── resources/
│   ├── css/               # Tailwind 4 CSS with design tokens
│   ├── js/                # JavaScript entry point
│   └── views/             # Blade templates
│       ├── layouts/       # App & guest layouts
│       ├── snippets/      # Snippet CRUD views
│       ├── dashboard/     # Dashboard views
│       ├── collections/   # Collection views
│       └── livewire/      # Livewire component views
├── routes/
│   ├── web.php            # Web routes
│   ├── api.php            # API routes (v1)
│   └── console.php        # Console commands & schedules
└── tests/
    ├── Feature/           # Feature tests
    └── Unit/              # Unit tests

---

Documentation

• Project Overview — Complete project specification including architecture, database design, features, API design, and design guidelines
• Implementation Checklist — Granular task tracker across all development phases

---

Development Roadmap

---

Design

CodeStash follows a custom design system built around the DIC brand identity:

• Colors: DIC Crimson (#7B1C3E), Forest Green (#2D6A4F), Gold (#D4920A) + warm neutrals
• Typography: Poppins (UI) + JetBrains Mono (code)
• Components: Cards, tags, code viewer, search bar — all with micro-animations
• Dark mode: Full support with lightened brand color variants for contrast

See Section 14 of the Project Overview for full design specifications.

---

Contributing & Forking

1. Fork the repository and create your feature branch: git checkout -b feature/my-cool-feature
2. Commit your changes following conventional commits: git commit -m "feat: added new awesome feature"
3. Push to your fork: git push origin feature/my-cool-feature
4. Submit a Pull Request against the main repository.

---

License

This project is proprietary software built for the Digital Innovation Center, UPLB.

---

Built with ❤️ by the DIC Team using Laravel 12, Filament 5, and Livewire 4.