231 lines
6.1 KiB
Markdown
231 lines
6.1 KiB
Markdown
# Counter - Habit Tracking Application
|
|
|
|
A full-stack web application for tracking habits and activities with counters. Users can create counters, increment/decrement them, and view statistics. The app supports both authenticated users (with database persistence) and anonymous users (with local storage).
|
|
|
|
## Features
|
|
|
|
- **User Authentication**: Register and login with JWT tokens
|
|
- **Anonymous Usage**: Work without registration using browser local storage
|
|
- **Counter Management**: Create, edit, delete, and manage counters
|
|
- **Increment/Decrement**: Track positive and negative changes
|
|
- **Date-based Tracking**: Counters store entries grouped by dates
|
|
- **Statistics**: View today, week, month, and total values
|
|
- **Search & Filter**: Find counters by name or description
|
|
- **Responsive Design**: Modern UI that works on all devices
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Go with Gin framework
|
|
- **Frontend**: React with TypeScript
|
|
- **Database**: PostgreSQL
|
|
- **Authentication**: JWT tokens
|
|
- **Deployment**: Docker with multi-stage builds
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose
|
|
- Go 1.21+ (for local development)
|
|
- Node.js 18+ (for local development)
|
|
|
|
### Using Docker Compose (Recommended)
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd counter
|
|
```
|
|
|
|
2. Start the application:
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
3. Open your browser and navigate to `http://localhost:8080`
|
|
|
|
The application will automatically:
|
|
- Start PostgreSQL database
|
|
- Build and run the Go backend
|
|
- Build and serve the React frontend
|
|
- Create necessary database tables
|
|
|
|
### Local Development
|
|
|
|
#### Backend Setup
|
|
|
|
1. Install dependencies:
|
|
```bash
|
|
go mod download
|
|
```
|
|
|
|
2. Start PostgreSQL (using Docker):
|
|
```bash
|
|
docker run --name counter-postgres -e POSTGRES_DB=counter_db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:15-alpine
|
|
```
|
|
|
|
3. Set environment variables:
|
|
```bash
|
|
export DATABASE_URL="postgres://postgres:password@localhost:5432/counter_db?sslmode=disable"
|
|
export JWT_SECRET="your-secret-key"
|
|
```
|
|
|
|
4. Run the backend:
|
|
```bash
|
|
go run .
|
|
```
|
|
|
|
#### Frontend Setup
|
|
|
|
1. Navigate to frontend directory:
|
|
```bash
|
|
cd frontend
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Start the development server:
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
4. Open `http://localhost:3000` in your browser
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/v1/auth/register` - Register a new user
|
|
- `POST /api/v1/auth/login` - Login user
|
|
- `GET /api/v1/auth/me` - Get current user (protected)
|
|
|
|
### Counters (Protected)
|
|
- `GET /api/v1/counters` - Get all counters
|
|
- `POST /api/v1/counters` - Create a new counter
|
|
- `GET /api/v1/counters/:id` - Get specific counter
|
|
- `PUT /api/v1/counters/:id` - Update counter
|
|
- `DELETE /api/v1/counters/:id` - Delete counter
|
|
- `POST /api/v1/counters/:id/increment` - Increment/decrement counter
|
|
- `GET /api/v1/counters/:id/entries` - Get counter entries
|
|
- `GET /api/v1/counters/:id/stats` - Get counter statistics
|
|
|
|
## Database Schema
|
|
|
|
### Users Table
|
|
- `id` (SERIAL PRIMARY KEY)
|
|
- `username` (VARCHAR(50) UNIQUE)
|
|
- `email` (VARCHAR(255) UNIQUE)
|
|
- `password` (VARCHAR(255))
|
|
- `created_at` (TIMESTAMP)
|
|
- `updated_at` (TIMESTAMP)
|
|
|
|
### Counters Table
|
|
- `id` (SERIAL PRIMARY KEY)
|
|
- `user_id` (INTEGER REFERENCES users(id))
|
|
- `name` (VARCHAR(100))
|
|
- `description` (TEXT)
|
|
- `created_at` (TIMESTAMP)
|
|
- `updated_at` (TIMESTAMP)
|
|
|
|
### Counter Entries Table
|
|
- `id` (SERIAL PRIMARY KEY)
|
|
- `counter_id` (INTEGER REFERENCES counters(id))
|
|
- `value` (INTEGER)
|
|
- `date` (DATE)
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
## Anonymous User Support
|
|
|
|
Anonymous users can use the application without registration:
|
|
- Counters are stored in browser's localStorage
|
|
- Data persists across browser sessions
|
|
- No server-side storage for anonymous users
|
|
- Seamless transition to authenticated user (data remains in localStorage)
|
|
|
|
## Environment Variables
|
|
|
|
Create a `.env` file based on `env.example`:
|
|
|
|
```bash
|
|
# Database Configuration
|
|
DATABASE_URL=postgres://postgres:password@localhost:5432/counter_db?sslmode=disable
|
|
|
|
# JWT Configuration
|
|
JWT_SECRET=your-super-secret-jwt-key-change-in-production
|
|
|
|
# Server Configuration
|
|
PORT=8080
|
|
GIN_MODE=release
|
|
```
|
|
|
|
## Deployment
|
|
|
|
### Production Deployment
|
|
|
|
1. Set environment variables for production
|
|
2. Use a production PostgreSQL database
|
|
3. Set a strong JWT secret
|
|
4. Build and deploy using Docker:
|
|
|
|
```bash
|
|
docker build -t counter-app .
|
|
docker run -p 8080:8080 \
|
|
-e DATABASE_URL="your-production-db-url" \
|
|
-e JWT_SECRET="your-production-secret" \
|
|
counter-app
|
|
```
|
|
|
|
### Docker Compose Production
|
|
|
|
Update `docker-compose.yml` with production settings:
|
|
- Use external PostgreSQL database
|
|
- Set production environment variables
|
|
- Configure proper networking and volumes
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
counter/
|
|
├── main.go # Main application entry point
|
|
├── models.go # Data models and DTOs
|
|
├── database.go # Database connection and setup
|
|
├── auth.go # Authentication handlers and middleware
|
|
├── counters.go # Counter management handlers
|
|
├── docker-compose.yml # Local development setup
|
|
├── Dockerfile # Multi-stage build for production
|
|
├── go.mod # Go dependencies
|
|
├── go.sum # Go dependencies checksum
|
|
└── frontend/ # React frontend
|
|
├── src/
|
|
│ ├── components/ # React components
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── services/ # API and localStorage services
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ └── App.tsx # Main React component
|
|
├── package.json # Node.js dependencies
|
|
└── public/ # Static assets
|
|
```
|
|
|
|
### Adding New Features
|
|
|
|
1. **Backend**: Add new handlers in appropriate files
|
|
2. **Frontend**: Create components in `src/components/`
|
|
3. **API Integration**: Update services in `src/services/`
|
|
4. **Types**: Add TypeScript interfaces in `src/types/`
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests if applicable
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License.
|