151 lines
4.2 KiB
Markdown
151 lines
4.2 KiB
Markdown
# 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]
|