akiyama-manga/INDEX.md

# 📚 Akiyama Manga - Complete Project

A modern manga hosting platform written in **Go**, with S3 integration and a design inspired by [yorai.io](https://yorai.io/). This is a production-ready application that supports uploading mangas to custom S3 buckets.

## 🎯 Quick Links

| Document | Purpose |
|----------|---------|
| [QUICKSTART.md](QUICKSTART.md) | Get running in 5 minutes |
| [README.md](README.md) | Full project documentation |
| [API.md](API.md) | REST API reference |
| [DATABASE_SETUP.md](DATABASE_SETUP.md) | PostgreSQL setup guide |
| [S3_SETUP.md](S3_SETUP.md) | AWS S3 configuration |
| [DEPLOYMENT.md](DEPLOYMENT.md) | Production deployment |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines |

## ✨ Features

### 🎨 Frontend
- **Dark theme UI** similar to yorai.io
- **Responsive design** for all devices
- **Search and filter** manga library
- **User authentication** system
- **Personal library** management
- **Review and rating** system

### 🔧 Backend
- **Go + Gin framework** for high performance
- **PostgreSQL database** with auto-migrations
- **JWT authentication** for security
- **S3 integration** for manga storage
- **RESTful API** endpoints
- **User profiles** and preferences

### ☁️ Storage
- **AWS S3 support**
- **Custom S3 endpoints** (MinIO, DigitalOcean, Linode, etc.)
- **Secure file uploads**
- **CDN-ready** URLs

### 🚀 Deployment
- **Docker & Docker Compose** ready
- **Linux systemd** service template
- **Nginx** reverse proxy config
- **Kubernetes** manifests included
- **Multiple deployment** options

## 📁 Project Structure

```
akiyama-manga/
├── cmd/server/                 # Application entry point
├── internal/
│   ├── auth/                  # JWT & authentication
│   ├── database/              # PostgreSQL setup
│   ├── handlers/              # HTTP request handlers
│   ├── middleware/            # CORS, auth middleware
│   ├── models/                # Database models
│   ├── services/              # Business logic
│   └── storage/               # S3 integration
├── web/frontend/
│   ├── static/
│   │   ├── css/              # Stylesheets
│   │   └── js/               # JavaScript
│   └── templates/            # HTML templates
├── migrations/               # Database migrations
├── Makefile                  # Build commands
├── Dockerfile                # Container image
├── docker-compose.yml        # Full stack
├── go.mod/go.sum            # Dependencies
└── docs/
    ├── README.md            # Main docs
    ├── QUICKSTART.md        # Quick setup
    ├── API.md              # API reference
    ├── DATABASE_SETUP.md   # DB setup
    ├── S3_SETUP.md         # S3 setup
    ├── DEPLOYMENT.md       # Deployment
    └── CONTRIBUTING.md     # Contributing
```

## 🚀 Getting Started

### Option 1: Docker (Fastest)

```bash
cd d:\Projects\akiyama-manga

# Copy environment file
copy .env.example .env

# Edit with your S3 credentials
notepad .env

# Start everything
docker-compose up

# Open http://localhost:8080
```

### Option 2: Local Development

```bash
# 1. Setup PostgreSQL (see DATABASE_SETUP.md)
# 2. Setup S3 credentials (see S3_SETUP.md)
# 3. Copy and configure .env
copy .env.example .env
notepad .env

# 4. Install and run
go mod download
go run cmd/server/main.go
```

### Option 3: Production

See [DEPLOYMENT.md](DEPLOYMENT.md) for:
- Linux systemd setup
- Nginx configuration
- Docker deployment
- Kubernetes setup
- Cloud platform guides

## 🔑 Key Configuration

### Environment Variables

```env
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=manga_user
DB_PASSWORD=your_password
DB_NAME=akiyama_manga

# S3 Storage
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1
S3_BUCKET_NAME=your_bucket
S3_ENDPOINT=https://s3.amazonaws.com

# Server
PORT=8080
JWT_SECRET=your_secret_key
GIN_MODE=debug
```

## 📚 Database Models

```
User ←→ Manga (many-to-many: user_library)
  │
  ├── Review → Manga
  └── Profile

Manga
  ├── Chapter → Page (stores S3 URLs)
  └── Tag (many-to-many: manga_tags)
```

## 🌐 API Endpoints

### Public
- `GET /api/mangas` - Browse all mangas
- `GET /api/mangas/:id` - Manga details
- `GET /api/mangas/:id/chapters/:num/pages` - Read chapter
- `GET /api/search?q=query` - Search mangas

### Authentication
- `POST /api/auth/signup` - Register
- `POST /api/auth/signin` - Login

### Protected (Requires JWT)
- `GET /api/library` - User's library
- `POST /api/library/:id` - Add to library
- `DELETE /api/library/:id` - Remove from library
- `POST /api/upload/manga` - Upload manga (admin)
- `POST /api/upload/chapter/:id` - Upload chapter (admin)

See [API.md](API.md) for complete documentation.

## 🛠️ Development

### Build Commands

```bash
make install-deps    # Install dependencies
make build          # Build application
make run            # Run application
make dev            # Development with hot reload
make test           # Run tests
make lint           # Run linter
make docker-build   # Build Docker image
```

### Development Workflow

1. **Backend changes**: Edit files in `internal/`
2. **Frontend changes**: Edit files in `web/frontend/`
3. **Database changes**: Modify models in `internal/models/models.go`
4. **API changes**: Update handlers and document in `API.md`

### Testing

```bash
go test -v ./...
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

## 📖 Documentation

### For Getting Started
→ Read [QUICKSTART.md](QUICKSTART.md)

### For API Usage
→ Read [API.md](API.md)

### For Database Setup
→ Read [DATABASE_SETUP.md](DATABASE_SETUP.md)

### For S3 Configuration
→ Read [S3_SETUP.md](S3_SETUP.md)

### For Production Deployment
→ Read [DEPLOYMENT.md](DEPLOYMENT.md)

### For Contributing
→ Read [CONTRIBUTING.md](CONTRIBUTING.md)

## 🐳 Docker Quick Reference

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f app

# Stop services
docker-compose down

# Remove volumes (WARNING: deletes data)
docker-compose down -v

# Rebuild containers
docker-compose build --no-cache

# Access PostgreSQL
docker-compose exec postgres psql -U manga_user -d akiyama_manga
```

## 🔐 Security Features

- JWT-based authentication
- Password hashing with bcrypt
- CORS middleware
- SQL injection prevention via GORM
- Environment variable configuration
- Rate limiting ready
- HTTPS support via Nginx reverse proxy

## 📊 Performance

- PostgreSQL for reliable data storage
- S3 for scalable image storage
- Efficient HTTP routing with Gin
- Database connection pooling support
- Static file caching
- Pagination for large datasets

## 🌍 Deployment Targets

- **Docker** (local & cloud)
- **Linux** (systemd service)
- **Heroku** (Git push deployment)
- **Kubernetes** (scalable)
- **AWS** (EC2, Fargate, Lambda)
- **DigitalOcean** (App Platform)
- **Railway** (Git-based)

## 🐛 Troubleshooting

### Port in use
```bash
# Change PORT in .env
PORT=8081
```

### Database connection failed
```bash
# Check PostgreSQL is running
psql -U manga_user -d akiyama_manga -h localhost
```

### S3 upload fails
See [S3_SETUP.md](S3_SETUP.md) troubleshooting section

### Build errors
```bash
go mod tidy
go mod download
```

## 📝 License

MIT License - Free to use and modify

## 🤝 Contributing

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📞 Support

- Check documentation in relevant `.md` files
- Review error logs with `docker-compose logs`
- Verify environment variables are set
- Test database and S3 connections

## 🎨 UI/UX Features

- **Dark theme** with accent colors (red/pink)
- **Responsive grid** layout for manga cards
- **Search bar** with keyboard shortcut (⌘K)
- **Navigation** with home, browse, library
- **Rating system** with star visualization
- **Featured** and recently updated sections
- **Smooth transitions** and hover effects
- **Mobile-first** design approach

## 🔄 Workflow

1. **Browse**: Users can search and browse manga
2. **Read**: Click manga to read chapters
3. **Rate**: Leave reviews and ratings
4. **Save**: Add to personal library
5. **Upload** (Admin): Add new manga and chapters to S3

## 🎯 Next Steps

1. Read [QUICKSTART.md](QUICKSTART.md)
2. Setup environment variables in `.env`
3. Run `docker-compose up` or follow local setup
4. Access application at `http://localhost:8080`
5. Create admin account and start uploading manga

---

**Ready to start?** → [QUICKSTART.md](QUICKSTART.md)

**Want to learn the API?** → [API.md](API.md)

**Deploying to production?** → [DEPLOYMENT.md](DEPLOYMENT.md)