# Documentation Index - Web Dolphin Japan

Quick guide to all documentation files and when to use them.

> **Backend API-Only Project:** All documentation covers the REST API backend development only. No frontend code or Node.js setup is required.

## 📚 Documentation Files

### 🚀 Getting Started

| File | Purpose | For Whom |
|------|---------|----------|
| [README.md](README.md) | **Project overview & quick start** | Everyone - start here |
| [SETUP.md](SETUP.md) | Detailed step-by-step installation guide | First-time setup |
| [QUICK_START.md](QUICK_START.md) | Command cheat sheet & common tasks | Developers after initial setup |
| [FAQ.md](FAQ.md) | Answers to common questions | Troubleshooting |

### 💻 Development

| File | Purpose | For Whom |
|------|---------|----------|
| [AGENTS.md](AGENTS.md) | Architecture & code conventions | Developers (reference) |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development workflow & standards | Contributors |
| [DEPLOYMENT.md](DEPLOYMENT.md) | Production deployment guide | DevOps / Release team |

### 🔧 GitHub & Automation

| File | Purpose | For Whom |
|------|---------|----------|
| [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) | PR submission format | GitHub integration |

---

## 🗺️ How to Use Documentation

### I'm new to this project
1. Read [README.md](README.md) - 5 minutes
2. Follow [SETUP.md](SETUP.md) - 15 minutes
3. Run `composer run setup` - 5-10 minutes
4. Start developing!

### I want to add a new feature
1. Review [AGENTS.md](AGENTS.md) for architecture
2. Follow [CONTRIBUTING.md](CONTRIBUTING.md) step-by-step
3. Use Brand example in [AGENTS.md](AGENTS.md) as reference
4. Create PR following [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md)

### I need a quick command
- Check [QUICK_START.md](QUICK_START.md)
- Common commands section with examples

### I'm stuck or something's broken
1. Check [FAQ.md](FAQ.md) - likely has your answer
2. Check [QUICK_START.md](QUICK_START.md) - common commands
3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - debugging section
4. Ask team members

### I'm deploying to production
1. Read [DEPLOYMENT.md](DEPLOYMENT.md)
2. Follow step-by-step guide
3. Use pre-deployment checklist
4. Monitor application after deployment

### I'm reviewing someone's PR
1. Check [CONTRIBUTING.md](CONTRIBUTING.md) - review checklist
2. Verify they followed [AGENTS.md](AGENTS.md) architecture
3. Run tests: `composer run test`
4. Check code style: `./vendor/bin/pint --test`

---

## 📋 Quick Document Summaries

### README.md (1-3 min read)
- **What it is**: Project overview and quick start
- **When to read**: First time, before setup
- **Key info**: Tech stack, quick setup command, project structure

### SETUP.md (15-20 min read)
- **What it is**: Step-by-step installation instructions
- **When to read**: During first-time setup
- **Key info**: Prerequisites, detailed setup steps, troubleshooting

### QUICK_START.md (2-3 min read)
- **What it is**: Command cheat sheet
- **When to use**: Daily - quick reference for commands
- **Key info**: Common dev tasks, database operations, testing

### FAQ.md (10-15 min read)
- **What it is**: Answers to frequently asked questions
- **When to read**: When you're stuck or confused
- **Key info**: Installation issues, development questions, common errors

### AGENTS.md (20-30 min read)
- **What it is**: Architecture guide & code conventions
- **When to read**: Before writing code, when adding features
- **Key info**: 3-layer architecture, naming conventions, file structure

### CONTRIBUTING.md (30-45 min read)
- **What it is**: Development workflow & standards
- **When to read**: Before making a PR, before reviewing code
- **Key info**: Feature implementation steps, testing, commit messages, PR process

### DEPLOYMENT.md (30-45 min read)
- **What it is**: Production deployment procedures
- **When to read**: Before deploying to production
- **Key info**: Pre-deployment checklist, step-by-step deployment, rollback

### .github/PULL_REQUEST_TEMPLATE.md
- **What it is**: GitHub PR template (auto-filled)
- **When used**: Automatically when creating PR on GitHub
- **Key info**: PR description format, checklist

---

## 🎯 Common Scenarios

### Scenario: "I'm new here, what do I do?"
**Time: 30 minutes**
1. Read [README.md](README.md) (5 min)
2. Follow [SETUP.md](SETUP.md) (20 min)
3. Run `composer run dev` and test (5 min)

### Scenario: "I want to add a new API endpoint"
**Time: 2-4 hours**
1. Review [AGENTS.md](AGENTS.md) architecture (15 min)
2. Follow [CONTRIBUTING.md](CONTRIBUTING.md) steps (1 hour)
3. Write code and tests (1-2 hours)
4. Create PR with template (15 min)

### Scenario: "Something is broken"
**Time: 5-30 minutes**
1. Check [FAQ.md](FAQ.md) (5 min)
2. Check [QUICK_START.md](QUICK_START.md) debugging section (5 min)
3. Check logs: `tail -f storage/logs/laravel.log` (5 min)
4. Ask team if still stuck (5 min)

### Scenario: "Ready to deploy"
**Time: 1-2 hours**
1. Review [DEPLOYMENT.md](DEPLOYMENT.md) (20 min)
2. Run pre-deployment checklist (10 min)
3. Follow deployment steps (30-60 min)
4. Verify deployment (10-15 min)

### Scenario: "Code review for a PR"
**Time: 15-30 minutes**
1. Check [CONTRIBUTING.md](CONTRIBUTING.md) review checklist (5 min)
2. Review code against [AGENTS.md](AGENTS.md) (10 min)
3. Run tests and linting (5 min)
4. Approve or request changes (5-10 min)

---

## 🔗 Documentation Links

**Quick Navigation:**
- [README.md](README.md) - Start here
- [SETUP.md](SETUP.md) - First-time installation
- [QUICK_START.md](QUICK_START.md) - Command reference
- [FAQ.md](FAQ.md) - Troubleshooting
- [AGENTS.md](AGENTS.md) - Architecture reference
- [CONTRIBUTING.md](CONTRIBUTING.md) - Development guide
- [DEPLOYMENT.md](DEPLOYMENT.md) - Production deployment

**External References:**
- [Laravel 12 Documentation](https://laravel.com/docs/12)
- [Eloquent ORM Guide](https://laravel.com/docs/12/eloquent)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

---

## 💡 Pro Tips

1. **Bookmark [QUICK_START.md](QUICK_START.md)** - You'll use it every day
2. **Keep [AGENTS.md](AGENTS.md) handy** - Reference for architecture
3. **Read [CONTRIBUTING.md](CONTRIBUTING.md) once** - Before first PR
4. **Check [FAQ.md](FAQ.md) first** - Before asking for help
5. **Use [DEPLOYMENT.md](DEPLOYMENT.md) checklist** - For production releases

---

## 📞 Getting Help

| Question | Check First |
|----------|-------------|
| How do I setup? | [SETUP.md](SETUP.md) |
| What command...? | [QUICK_START.md](QUICK_START.md) |
| How do I add a feature? | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Something's broken | [FAQ.md](FAQ.md) |
| Code structure? | [AGENTS.md](AGENTS.md) |
| Deploying to production? | [DEPLOYMENT.md](DEPLOYMENT.md) |
| Still stuck? | Ask team in discussions |

---

## 📝 Document Maintenance

**Last Updated:** May 5, 2026

**How to keep docs updated:**
- Update when you discover new solutions
- Update when procedures change
- Keep examples current
- Test all instructions before updating

**Contributors:** Web Dolphin Japan Development Team

---

**Ready to get started?** → [README.md](README.md)
