README and UI README from the robot with project details

2025-06-13 23:19:01 -07:00
parent 43ceca86e0
commit 1e90cbbb39
3 changed files with 437 additions and 43 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,199 @@
 # glancr
-A Markdown documentation viewer written in Go and React.
+
+A modern Markdown documentation viewer built with Go and React. **glancr** provides a clean, fast interface for browsing and viewing Markdown documentation with live reload capabilities during development.
+
+## Features
+
+- 🚀 **Fast & Lightweight** - Single binary deployment with embedded assets
+- 📝 **Markdown Rendering** - Beautiful rendering of Markdown documents
+- 🔄 **Live Development** - Hot reload during development
+- 🎨 **Modern UI** - Clean, responsive React-based interface
+- 📱 **Mobile Friendly** - Responsive design that works on all devices
+- 🔧 **Easy Setup** - Simple development and deployment workflow
+
+## Prerequisites
+
+- **Go** 1.19+ 
+- **Node.js** 18+ and npm
+- **Git**
+
+## Quick Start
+
+### Development
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/smjklake/glancr.git
+   cd glancr
+   ```
+
+2. **Install dependencies**
+   ```bash
+   make deps
+   ```
+
+3. **Start development servers**
+   ```bash
+   make dev
+   ```
+
+   This will start:
+   - Frontend dev server at http://localhost:5173
+   - Backend API server at http://localhost:8080
+
+### Production Build
+
+1. **Build for production**
+   ```bash
+   make build-prod
+   ```
+
+2. **Run the binary**
+   ```bash
+   ./dist/glancr
+   ```
+
+   The application will be available at http://localhost:8080
+
+## Available Commands
+
+### Development
+- `make dev` - Start development environment with live reload
+- `make build-dev` - Build development version (filesystem assets)
+- `make test` - Run Go tests
+
+### Production  
+- `make build-prod` - Build production version (embedded assets)
+- `make release` - Clean build for production release
+- `make build-cross-prod` - Build for multiple platforms
+
+### Utilities
+- `make clean` - Clean build artifacts
+- `make clean-all` - Deep clean including node_modules
+- `make deps` - Install all dependencies
+- `make help` - Show all available commands
+
+## Project Structure
+
+```
+glancr/
+├── cmd/
+│   └── server/          # Application entry point
+│       └── main.go
+├── internal/            # Private application code
+│   ├── auth/           # Authentication logic
+│   └── fs/             # Asset handling (dev/prod)
+├── ui/                 # React frontend
+│   ├── src/
+│   ├── public/
+│   └── package.json
+├── dist/               # Build output
+├── Makefile           # Build automation
+├── dev.sh             # Development script
+└── go.mod             # Go module definition
+```
+
+## Architecture
+
+**glancr** uses a clean architecture with clear separation between frontend and backend:
+
+- **Backend (Go)**: Serves the React SPA and provides API endpoints
+- **Frontend (React)**: Modern TypeScript-based UI with Vite tooling
+- **Asset Handling**: Development mode serves from filesystem, production embeds assets in binary
+- **Build System**: Makefile orchestrates both Go and Node.js build processes
+
+## Development Workflow
+
+### Adding Features
+
+1. **Backend changes**: Add logic in `internal/` packages
+2. **Frontend changes**: Modify React components in `ui/src/`
+3. **API endpoints**: Update server routes in `cmd/server/main.go`
+
+### Testing
+
+```bash
+# Run Go tests
+make test
+
+# Run with production build tags
+make test-prod
+
+# Run all tests
+make test-all
+```
+
+### Code Quality
+
+The frontend includes:
+- **ESLint** for code linting
+- **Prettier** for code formatting  
+- **TypeScript** for type safety
+
+```bash
+cd ui
+npm run lint          # Check for linting issues
+npm run lint:fix      # Fix auto-fixable issues
+npm run format        # Format code with Prettier
+```
+
+## Deployment
+
+### Single Binary Deployment
+
+Build and deploy the production binary:
+
+```bash
+make release
+scp dist/glancr user@server:/path/to/deployment/
+```
+
+### Cross-Platform Builds
+
+Generate binaries for multiple platforms:
+
+```bash
+make build-cross-prod
+```
+
+Produces:
+- `glancr-linux-amd64`
+- `glancr-darwin-amd64` 
+- `glancr-darwin-arm64`
+- `glancr-windows-amd64.exe`
+
+## Configuration
+
+Currently **glancr** runs with minimal configuration. The server starts on port 8080 by default.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`make test`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Development Guidelines
+
+- Follow Go conventions and use `gofmt`
+- Write tests for new functionality
+- Use TypeScript for frontend development
+- Run `make lint` before committing
+- Keep commits atomic and well-described
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Go](https://golang.org/) and [React](https://reactjs.org/)
+- Bundled with [Vite](https://vitejs.dev/)
+- Styled with modern CSS practices
+
+---
+
+**glancr** - Making documentation beautiful, one markdown file at a time. ✨