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. This is a production-ready application that supports uploading mangas to custom S3 buckets.

🎯 Quick Links

Document	Purpose
QUICKSTART.md	Get running in 5 minutes
README.md	Full project documentation
API.md	REST API reference
DATABASE_SETUP.md	PostgreSQL setup guide
S3_SETUP.md	AWS S3 configuration
DEPLOYMENT.md	Production deployment
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)

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

# 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 for:

• Linux systemd setup
• Nginx configuration
• Docker deployment
• Kubernetes setup
• Cloud platform guides

🔑 Key Configuration

Environment Variables

# 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 for complete documentation.

🛠️ Development

Build Commands

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

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

📖 Documentation

For Getting Started

→ Read QUICKSTART.md

For API Usage

→ Read API.md

For Database Setup

→ Read DATABASE_SETUP.md

For S3 Configuration

→ Read S3_SETUP.md

For Production Deployment

→ Read DEPLOYMENT.md

For Contributing

→ Read CONTRIBUTING.md

🐳 Docker Quick Reference

# 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

# Change PORT in .env
PORT=8081

Database connection failed

# Check PostgreSQL is running
psql -U manga_user -d akiyama_manga -h localhost

S3 upload fails

See S3_SETUP.md troubleshooting section

Build errors

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 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
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

Want to learn the API? → API.md

Deploying to production? → DEPLOYMENT.md