Update README with comprehensive project documentation

- Add detailed feature overview (wiki-links, folders, multi-language, responsive) - Include complete installation and setup instructions - Document project structure and key concepts - Add development workflow and common commands - Include troubleshooting section - Update technology stack and credits 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-30 13:19:43 +09:00
parent e14cc5dd43
commit 33fef93ce0
1 changed files with 314 additions and 41 deletions
--- a/src/README.md
+++ b/src/README.md
@@ -1,59 +1,332 @@
-<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
+# Knowledge Base System

-<p align="center">
-<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
-</p>
+An Obsidian-like knowledge base system built with Laravel 12, Livewire v3, and Alpine.js. Create, organize, and link your documents with wiki-style references and a powerful search interface.

-## About Laravel
+## Features

-Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
+### Core Functionality
+- **Markdown-based documents** with live preview using EasyMDE editor
+- **Wiki-style linking** with `[[Document Title]]` syntax
+- **Automatic backlinks** - see which documents reference the current page
+- **Folder organization** - use `/` in titles to auto-organize into folders (e.g., `Laravel/Livewire/Components`)
+- **Quick switcher** - Press `Ctrl+K` to instantly search and navigate
+- **Full-text search** - MySQL FULLTEXT index with ngram tokenizer for multilingual support
+- **ID-based routing** - Clean URLs with guaranteed uniqueness

- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
+### Multi-Language Support
+Interface available in **16 languages**:
+- English, 日本語 (Japanese)
+- 简体中文, 繁體中文 (Simplified/Traditional Chinese)
+- 한국어 (Korean)
+- हिन्दी (Hindi), Tiếng Việt (Vietnamese), Türkçe (Turkish)
+- Deutsch, Français, Español, Português (Brasil)
+- Русский, Українська, Italiano, Polski

-Laravel is accessible, powerful, and provides tools required for large, robust applications.
+Language preferences persist for both authenticated and guest users via cookies.

-## Learning Laravel
+### Responsive Design
+- **Mobile-first** interface with hamburger menu
+- **Tablet and desktop** optimized layouts
+- **Touch-friendly** navigation
+- All features work seamlessly across devices

-Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.
+### User Management
+- **Role-based access** - Admin and regular user roles
+- **User authentication** - Laravel Breeze integration
+- **Profile management** - Update name, email, password, and language preference

-If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
+## Technology Stack

-## Laravel Sponsors
+- **Backend**: Laravel 12.0 (PHP 8.2+)
+- **Frontend**: Livewire v3.7.0, Alpine.js, Tailwind CSS
+- **Database**: MySQL 8.0 with FULLTEXT indexing
+- **Markdown**: league/commonmark for rendering
+- **Editor**: EasyMDE (markdown editor)
+- **Docker**: Custom containerized environment

-We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
+## Prerequisites

-### Premium Partners
+- Docker and Docker Compose
+- Node.js 18+ (for asset compilation)
+- Git

- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**
+## Installation
+
+### 1. Clone the repository
+
+```bash
+git clone <repository-url>
+cd knowledge-base
+```
+
+### 2. Start Docker services
+
+```bash
+docker compose up -d
+```
+
+This starts:
+- Nginx: `http://localhost:9700`
+- phpMyAdmin: `http://localhost:9701`
+- MySQL: `localhost:9702`
+- MailHog: `http://localhost:9725`
+
+### 3. Install dependencies
+
+```bash
+# Inside the src/ directory
+cd src
+
+# Install PHP dependencies
+docker compose exec php composer install
+
+# Install Node dependencies
+npm install
+```
+
+### 4. Configure environment
+
+```bash
+# Copy environment file
+cp .env.example .env
+
+# Generate application key
+docker compose exec php php artisan key:generate
+```
+
+### 5. Set up database
+
+```bash
+# Run migrations
+docker compose exec php php artisan migrate
+
+# Seed initial user (admin@example.com / password)
+docker compose exec php php artisan db:seed --class=UserSeeder
+
+# Initialize sample documents (optional)
+docker compose exec php php artisan docs:init
+```
+
+### 6. Build frontend assets
+
+```bash
+# Development mode with hot reload
+npm run dev
+
+# Or production build
+npm run build
+```
+
+### 7. Access the application
+
+Open `http://localhost:9700` in your browser.
+
+**Default credentials**:
+- Email: `admin@example.com`
+- Password: `password`
+
+## Development
+
+### Running the dev environment
+
+```bash
+# Start all services (server, queue, logs, Vite)
+docker compose exec php composer dev
+```
+
+### Running tests
+
+```bash
+docker compose exec php php artisan test
+```
+
+### Common commands
+
+```bash
+# Access PHP container shell
+docker compose exec php bash
+
+# Clear caches
+docker compose exec php php artisan config:clear
+docker compose exec php php artisan cache:clear
+docker compose exec php php artisan view:clear
+
+# Publish Livewire assets (after updates)
+docker compose exec php php artisan livewire:publish --assets
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── Http/
+│   │   ├── Controllers/
+│   │   │   └── LocaleController.php      # Language switching
+│   │   └── Middleware/
+│   │       └── SetLocale.php              # Multi-language support
+│   ├── Livewire/
+│   │   ├── DocumentEditor.php             # Create/edit documents
+│   │   ├── DocumentViewer.php             # Display documents
+│   │   ├── QuickSwitcher.php              # Ctrl+K search modal
+│   │   └── SidebarTree.php                # Folder tree navigation
+│   ├── Models/
+│   │   ├── Document.php                   # Document model
+│   │   ├── DocumentLink.php               # Wiki-style links
+│   │   └── RecentDocument.php             # Access history
+│   └── Services/
+│       └── DocumentService.php            # Document business logic
+├── database/
+│   └── migrations/                        # Database schema
+├── lang/                                  # Translation files (16 languages)
+├── resources/
+│   ├── css/
+│   │   └── app.css                        # Tailwind + custom styles
+│   ├── js/
+│   │   └── app.js                         # Alpine.js initialization
+│   └── views/
+│       ├── layouts/
+│       │   └── knowledge-base.blade.php   # Main layout
+│       └── livewire/                      # Livewire component views
+└── routes/
+    └── web.php                            # Application routes
+```
+
+## Key Concepts
+
+### Document Organization
+
+Documents are organized using **virtual paths** derived from titles:
+
+```php
+Title: "Laravel/Livewire/Components"
+→ Path: "Laravel/Livewire/Components.md"
+→ Slug: "components"
+→ Sidebar: Nested under Laravel → Livewire → Components
+```
+
+No manual directory field needed - just use `/` in the title!
+
+### Wiki-Style Links
+
+Create links between documents using double brackets:
+
+```markdown
+See [[Getting Started]] for more information.
+Links to [[Uncreated Pages]] appear in red.
+```
+
+Links are automatically:
+- Extracted and stored in the `document_links` table
+- Rendered as clickable HTML anchors
+- Displayed as backlinks on target documents
+
+### ID-Based Routing
+
+URLs use document IDs instead of slugs:
+
+```
+/documents/123        (instead of /documents/my-document-slug)
+```
+
+Benefits:
+- Guaranteed uniqueness
+- Title changes don't break URLs
+- Simpler route model binding
+
+### Folder State Persistence
+
+Sidebar folder expanded/collapsed state is stored in `localStorage`:
+
+```javascript
+// Managed by Alpine.js
+localStorage.getItem('kb_expanded_folders')
+// ["Laravel", "Laravel/Livewire", "Docker"]
+```
+
+Survives page navigation and browser sessions.
+
+## Customization
+
+### Adding new languages
+
+1. Add to `SetLocale::SUPPORTED_LOCALES` in `app/Http/Middleware/SetLocale.php`
+2. Create translation file at `lang/{code}/messages.php`
+3. Copy structure from existing language file
+
+### Changing default locale
+
+Edit `config/app.php`:
+
+```php
+'locale' => 'en',  // Change to your preferred language code
+```
+
+### Customizing markdown styles
+
+Edit `resources/css/app.css`:
+
+```css
+@layer components {
+    .prose .wiki-link {
+        @apply text-indigo-600 hover:text-indigo-800 underline;
+    }
+}
+```
+
+## Troubleshooting
+
+### Livewire assets not loading
+
+```bash
+docker compose exec php php artisan livewire:publish --assets
+```
+
+### Frontend changes not reflecting
+
+```bash
+npm run build
+docker compose exec php php artisan view:clear
+```
+
+### Database connection errors
+
+Check `.env` file matches Docker Compose settings:
+
+```env
+DB_CONNECTION=mysql
+DB_HOST=kb_mysql
+DB_PORT=3306
+DB_DATABASE=knowledge_base
+DB_USERNAME=kb_user
+DB_PASSWORD=kb_password
+```
+
+### Alpine.js errors in console
+
+Ensure scripts are loaded in correct order in `knowledge-base.blade.php`:
+1. Livewire scripts first
+2. Alpine.js initialization (via Vite)
+3. Custom Alpine components

 ## Contributing

-Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
-
-## Code of Conduct
-
-In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
-
-## Security Vulnerabilities
-
-If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
+Contributions are welcome! Please ensure:
+- Code follows Laravel and PSR-12 conventions
+- All existing tests pass
+- New features include tests
+- UI changes maintain responsive design

 ## License

-The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
+This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Built with:
+- [Laravel](https://laravel.com) - The PHP Framework
+- [Livewire](https://livewire.laravel.com) - Full-stack framework for Laravel
+- [Alpine.js](https://alpinejs.dev) - Lightweight JavaScript framework
+- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
+- [EasyMDE](https://github.com/Ionaru/easy-markdown-editor) - Markdown editor
+- [league/commonmark](https://commonmark.thephpleague.com) - Markdown parser