Initial commit: Custom Start Page application with authentication and DynamoDB storage

2026-02-18 22:06:43 -05:00
commit 7175ff14ba
47 changed files with 7592 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,150 @@
+# Custom Start Page Application
+
+A personalized dashboard web application that allows users to create and manage custom start pages with configurable widgets, multiple pages, and customizable search functionality.
+
+## Features
+
+- **OAuth Authentication**: Secure login with Google OAuth (extensible to other providers)
+- **Multi-Page Dashboard**: Organize widgets across multiple pages
+- **Widget System**: Bookmark, Notes, and Weather widgets
+- **Tag System**: Organize bookmarks and notes with tags
+- **Group System**: Group bookmarks within widgets
+- **Rich Content**: Support for plain text, RTF, code, YAML, and Markdown in notes
+- **Sharing**: Share bookmarks and notes with others
+- **Responsive Design**: Works on desktop, tablet, and mobile devices
+
+## Technology Stack
+
+- **Backend**: Go 1.26+
+- **Frontend**: HTMX, Tailwind CSS, Vanilla JavaScript
+- **Database**: AWS DynamoDB (with DynamoDB Local for development)
+- **Testing**: Go testing package + gopter for property-based tests
+
+## Prerequisites
+
+- Go 1.26 or higher (installed at `/usr/local/go/bin/go`)
+- Docker and Docker Compose (for DynamoDB Local)
+- Google OAuth credentials (for authentication)
+
+## Getting Started
+
+### 1. Clone the repository
+
+```bash
+git clone <repository-url>
+cd custom-start-page
+```
+
+### 2. Set up environment variables
+
+```bash
+cp .env.example .env
+# Edit .env and add your Google OAuth credentials
+```
+
+### 3. Start DynamoDB Local
+
+```bash
+make db-start
+```
+
+### 4. Install dependencies
+
+```bash
+make deps
+```
+
+### 5. Run the application
+
+```bash
+make dev
+```
+
+The application will be available at `http://localhost:8080`
+
+## Development
+
+### Available Make Commands
+
+- `make help` - Show available commands
+- `make build` - Build the application
+- `make run` - Run the application
+- `make test` - Run all tests
+- `make test-coverage` - Run tests with coverage report
+- `make dev` - Start development environment (DynamoDB + server)
+- `make db-start` - Start DynamoDB local
+- `make db-stop` - Stop DynamoDB local
+- `make db-reset` - Reset DynamoDB local data
+- `make deps` - Download dependencies
+- `make fmt` - Format code
+- `make clean` - Clean build artifacts
+
+### Project Structure
+
+```
+.
+├── cmd/
+│   └── server/          # Main application entry point
+├── internal/
+│   ├── auth/            # Authentication logic
+│   ├── handlers/        # HTTP handlers
+│   ├── models/          # Data models
+│   ├── services/        # Business logic
+│   ├── storage/         # Database layer
+│   └── testing/         # Test helpers
+├── pkg/
+│   └── config/          # Configuration management
+├── templates/
+│   ├── layouts/         # Base HTML templates
+│   ├── partials/        # Reusable template components
+│   └── widgets/         # Widget templates
+├── static/
+│   ├── css/             # Stylesheets
+│   ├── js/              # JavaScript files
+│   └── images/          # Static images
+├── docker-compose.yml   # DynamoDB Local setup
+├── Makefile            # Development commands
+└── README.md           # This file
+```
+
+## Testing
+
+The project uses both unit tests and property-based tests:
+
+```bash
+# Run all tests
+make test
+
+# Run tests with coverage
+make test-coverage
+```
+
+Property-based tests use [gopter](https://github.com/leanovate/gopter) to verify correctness properties across many generated inputs.
+
+## Configuration
+
+Configuration is managed through environment variables. See `.env.example` for available options:
+
+- `PORT` - Server port (default: 8080)
+- `HOST` - Server host (default: localhost)
+- `DYNAMODB_ENDPOINT` - DynamoDB endpoint (default: http://localhost:8000)
+- `GOOGLE_CLIENT_ID` - Google OAuth client ID
+- `GOOGLE_CLIENT_SECRET` - Google OAuth client secret
+- `SESSION_SECRET` - Session encryption key
+
+## Architecture
+
+The application follows a hypermedia-driven architecture:
+
+- **Server-side rendering**: HTML templates rendered by Go
+- **HTMX**: Dynamic interactions without complex JavaScript
+- **DynamoDB**: Scalable NoSQL database for user data
+- **OAuth**: Secure authentication with external providers
+
+## License
+
+[Add your license here]
+
+## Contributing
+
+[Add contribution guidelines here]