# RealWorld Full Stack Application A Medium.com clone built with React + Go + SQLite, following the [RealWorld specification](https://realworld-docs.netlify.app/). ## Overview This is a full-stack implementation of the RealWorld application demonstrating: - Modern React with TypeScript and Vite - Go backend with standard library HTTP server - SQLite database with migrations - JWT authentication - RESTful API design - Production-ready architecture ## Implementation Progress ### ✅ Phase 1.1: Project Setup & Foundation (Completed) - [x] Project structure created - [x] Go backend with HTTP server - [x] SQLite database with schema - [x] JWT authentication middleware - [x] User models and validation - [x] Basic handler structure ### 🔄 Next: Phase 1.2: Authentication System - [ ] User registration endpoint - [ ] User login endpoint - [ ] Protected routes - [ ] Profile management ### ⏳ Upcoming Phases - Phase 1.3: Articles CRUD & Feed - Phase 1.4: Comments & Tags System - Phase 2.1: Frontend Setup - Phase 2.2: Authentication Pages - Phase 2.3: Article Feeds - Phase 3.1: Testing & Quality - Phase 3.2: Production Ready ## Demo & Resources - **RealWorld Spec**: [github.com/gothinkster/realworld](https://github.com/gothinkster/realworld) - **API Documentation**: [docs.realworld.show](https://docs.realworld.show/) - **Project PRD**: [docs/PRD.md](./docs/PRD.md) - **System Design**: [docs/DESIGN.md](./docs/DESIGN.md) ## Tech Stack ### Frontend - **React 18+** with TypeScript for type-safe component development - **Vite** for fast development and optimized production builds - **TanStack Router** for type-safe, hash-based routing - **TanStack Query** for efficient server state management - **Tailwind CSS** for utility-first styling - **Shadcn/UI** for consistent, accessible UI components - **Lucide React** for modern iconography ### Backend - **Go 1.25+** with standard library HTTP server - **SQLite** for lightweight, file-based data storage - **JWT authentication** with secure token management - **bcrypt** for password hashing - **Plain SQL** with prepared statements (no ORM complexity) ### Development & Deployment - **Docker** with multi-stage builds for development and production - **Hot Module Replacement** for fast development iteration - **Vitest** for frontend testing - **Go testing** for backend unit and integration tests - **Playwright** for end-to-end testing ## Features This RealWorld implementation includes all the standard features: - � **Authentication** - Register, login, logout with JWT - � **Profile Management** - User profiles with bio, image, follow/unfollow - � **Article Management** - Create, read, update, delete articles with markdown - � **Social Features** - Favorite articles, follow users, comment system - � **Content Discovery** - Global feed, personal feed, tag-based filtering - � **Responsive Design** - Mobile-first, cross-device compatibility ## Quick Start ### Prerequisites - **Docker** and **Docker Compose** - **Git** for version control ### Development Setup 1. **Clone the repository** ```bash git clone https://github.com/diki816/realworld-build-from-prd.git cd realworld-build-from-prd ``` 2. **Start the development environment** ```bash docker-compose up ``` 3. **Access the application** - Frontend: http://localhost:3000 - Backend API: http://localhost:8080 - API Base URL: http://localhost:8080/api ### Manual Development (without Docker) **Backend Setup:** ```bash cd backend go mod download go run cmd/server/main.go ``` **Frontend Setup:** ```bash cd frontend npm install npm run dev ``` ## Project Structure ``` realworld-build-from-prd/ � docs/ # Documentation � � PRD.md # Product Requirements Document � � tasks.md # Implementation task breakdown � frontend/ # React + TypeScript frontend � � src/ � � � components/ # Reusable UI components � � � pages/ # Route components � � � hooks/ # Custom React hooks � � � lib/ # Utilities and API client � � � types/ # TypeScript type definitions � � package.json � � vite.config.ts � backend/ # Go backend API � � cmd/server/ # Application entry point � � internal/ � � � handlers/ # HTTP request handlers � � � middleware/ # HTTP middleware � � � models/ # Data models � � � database/ # Database setup and queries � � � utils/ # Helper functions � � tests/ # Backend tests � � go.mod � � go.sum � data/ # SQLite database files � docker-compose.yml # Development environment � README.md ``` ## Architecture Principles This implementation follows key architectural principles: ### Agent-Friendly Design - **Function-first approach** over complex object hierarchies - **Explicit context usage** for request scoping - **Clear error handling** with consistent patterns - **Minimal dependencies** - "dumbest thing that works" ### Performance & Security - **Type-safe development** with TypeScript and Go - **Optimized queries** with proper database indexing - **JWT-based authentication** with secure token handling - **Input validation** and XSS protection - **CORS configuration** for cross-origin requests ### Modern Development Practices - **Component-driven development** with Shadcn/UI - **Server state management** with TanStack Query - **Code splitting** and lazy loading for performance - **Comprehensive testing** strategy across all layers ## API Endpoints The backend implements the complete RealWorld API specification: ### Authentication - `POST /api/users/login` - User login - `POST /api/users` - User registration - `GET /api/user` - Get current user (requires auth) - `PUT /api/user` - Update user (requires auth) ### Profiles - `GET /api/profiles/:username` - Get user profile - `POST /api/profiles/:username/follow` - Follow user (requires auth) - `DELETE /api/profiles/:username/follow` - Unfollow user (requires auth) ### Articles - `GET /api/articles` - List articles (with filtering & pagination) - `GET /api/articles/feed` - Get user feed (requires auth) - `GET /api/articles/:slug` - Get single article - `POST /api/articles` - Create article (requires auth) - `PUT /api/articles/:slug` - Update article (requires auth) - `DELETE /api/articles/:slug` - Delete article (requires auth) ### Social Features - `POST /api/articles/:slug/favorite` - Favorite article (requires auth) - `DELETE /api/articles/:slug/favorite` - Unfavorite article (requires auth) - `GET /api/articles/:slug/comments` - Get article comments - `POST /api/articles/:slug/comments` - Add comment (requires auth) - `DELETE /api/articles/:slug/comments/:id` - Delete comment (requires auth) ### Tags - `GET /api/tags` - Get all tags ## Testing Run the test suites: ```bash # Backend tests cd backend go test ./... # Frontend tests cd frontend npm run test # E2E tests cd frontend npm run test:e2e ``` ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgments - **RealWorld** - For providing the comprehensive specification and community - **Dt� \��** - For defining the technical stack and development approach - **Shadcn** - For the excellent UI component system - **TanStack** - For the powerful React libraries (Query, Router) --- > =� **Learning Resource**: This project serves as a comprehensive example of modern full-stack development, demonstrating real-world patterns beyond basic tutorials.