https://github.com/montasim/github-readme-counter
A simple web service that generates a dynamic SVG image showing a visitor count. It increments a counter every time the endpoint is called and returns an SVG image displaying the updated count.
https://github.com/montasim/github-readme-counter
api counter customizable-svg dynamic-svg expressjs github glitch nodejs real-time server svg visitor-counter web-application web-service
Last synced: 3 months ago
JSON representation
A simple web service that generates a dynamic SVG image showing a visitor count. It increments a counter every time the endpoint is called and returns an SVG image displaying the updated count.
- Host: GitHub
- URL: https://github.com/montasim/github-readme-counter
- Owner: montasim
- License: bsd-3-clause
- Created: 2024-06-25T10:48:55.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-25T05:17:32.000Z (almost 2 years ago)
- Last Synced: 2025-02-09T20:36:44.956Z (over 1 year ago)
- Topics: api, counter, customizable-svg, dynamic-svg, expressjs, github, glitch, nodejs, real-time, server, svg, visitor-counter, web-application, web-service
- Language: JavaScript
- Homepage: https://plum-meowing-freon.glitch.me/count.svg
- Size: 24.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# GitHub Readme Counter
A modern, well-architected web service that generates dynamic SVG images showing visitor counts. Built with Express.js following Clean Code principles, SOLID design patterns, and industry best practices.
## โจ Features
- **Dynamic SVG Generation**: Creates customizable SVG images with visitor counts
- **Real-time Counter**: Increments on each request with persistent storage
- **Customizable Appearance**: Customize background and text colors via URL parameters
- **Health Check Endpoint**: Monitor service status and uptime
- **Comprehensive Error Handling**: Proper HTTP status codes and error messages
- **Request Logging**: Detailed logging with color-coded status codes
- **Input Validation**: Validates hex color codes with proper error messages
- **Graceful Shutdown**: Handles termination signals properly
- **Backward Compatible**: Supports both old and new query parameter formats
## ๐๏ธ Architecture
This project follows a modular, layered architecture with clear separation of concerns:
```
src/
โโโ config/ # Configuration management
โ โโโ constants.js # Magic numbers, default values, SVG config
โ โโโ paths.js # Path configurations
โ โโโ index.js # Export all configs
โโโ services/ # Business logic layer
โ โโโ CounterService.js # Counter operations (read/write/increment)
โ โโโ ImageService.js # SVG generation
โโโ controllers/ # Request handling layer
โ โโโ CounterController.js # HTTP request handler
โโโ routes/ # Route definitions
โ โโโ counterRoutes.js # Counter endpoint routes
โ โโโ healthRoutes.js # Health check endpoint
โ โโโ index.js # Export all routes
โโโ middleware/ # Express middleware
โ โโโ errorHandler.js # Global error handling
โ โโโ logger.js # Request/response logging
โ โโโ notFound.js # 404 handler
โโโ utils/ # Utility functions
โ โโโ validators.js # Input validation
โ โโโ helpers.js # Helper functions
โโโ app.js # Express app setup
โโโ index.js # Entry point with graceful shutdown
โโโ counter.txt # Counter storage
```
### Design Principles
- **Single Responsibility Principle**: Each module has a single, well-defined purpose
- **Open/Closed Principle**: Easy to extend without modifying existing code
- **Dependency Inversion**: High-level modules don't depend on low-level modules
- **Clean Code**: Meaningful names, small functions, comprehensive documentation
- **Express.js Best Practices**: Proper middleware chain, error handling, and logging
## ๐ ๏ธ Requirements
- [Node.js](https://nodejs.org/en) (>= 20.x)
- [pnpm](https://pnpm.io/) (>= 8.x)
## ๐ Installation
1. **Clone the repository**:
```bash
git clone https://github.com/montasim/github-readme-counter.git
cd github-readme-counter
```
2. **Install dependencies**:
```bash
pnpm install
```
3. **Start the server**:
```bash
pnpm start
```
For development with auto-reload:
```bash
pnpm dev
```
The server will start on the port specified in your environment variables or default to port 3000.
## ๐ก API Endpoints
### Health Check
Check the service status and uptime:
```bash
GET /health
```
**Response**:
```json
{
"status": "ok",
"timestamp": "2026-02-23T05:00:00.000Z",
"uptime": 123.456
}
```
### Counter SVG
Get a dynamic SVG image with the visitor count:
```bash
GET /count.svg
```
**Query Parameters**:
| Parameter | Short | Description | Default |
|-----------|-------|-------------|---------|
| Background Color | `bg` | Hex code for background color | `000000` (black) |
| Text Color | `tc` | Hex code for text color | `EB008B` (magenta) |
> **Note**: For backward compatibility, the old parameter names (`backgroundColor` and `textColor`) are still supported. The new short names take precedence if both are provided.
**Examples**:
Default colors:
```bash
http://localhost:3000/count.svg
```
Custom colors (new parameters):
```bash
http://localhost:3000/count.svg?bg=FFFFFF&tc=0000FF
```
Custom colors (old parameters - still supported):
```bash
http://localhost:3000/count.svg?backgroundColor=FFFFFF&textColor=0000FF
```
Mixed parameters (new takes precedence):
```bash
http://localhost:3000/count.svg?bg=FFFFFF&textColor=0000FF
```
## ๐จ Customization
### Color Guidelines
- Provide hex codes **without** the `#` symbol (e.g., `FFFFFF`, not `#FFFFFF`)
- Use 6-digit hex codes (e.g., `000000`, `FFFFFF`, `EB008B`)
- Invalid or unsupported color values will revert to defaults
### Color Examples
| Color | Hex Code | Preview |
|-------|----------|---------|
| Black | `000000` | โฌ |
| White | `FFFFFF` | โฌ |
| Red | `FF0000` | ๐ฅ |
| Green | `00FF00` | ๐ฉ |
| Blue | `0000FF` | ๐ฆ |
| Magenta | `EB008B` | ๐ |
| Cyan | `00B8B5` | ๐ |
## ๐งช Testing
All features have been tested and verified:
โ
**Health Check Endpoint**
- Returns 200 status
- Includes service status, timestamp, and uptime
โ
**Counter Endpoint**
- Returns SVG image with incremented counter
- Default colors work correctly
- Custom colors apply properly
โ
**Query Parameters**
- New short parameters (`bg`, `tc`) work
- Old long parameters (`backgroundColor`, `textColor`) work
- Mixed parameters work (new takes precedence)
- No parameters use defaults
โ
**Error Handling**
- Invalid hex codes return 400 status
- Proper error messages displayed
- Error logging with stack traces
โ
**404 Handler**
- Undefined routes return 404 status
- Consistent 404 response format
โ
**Logging**
- All requests logged with timestamp and method
- All responses logged with status code and duration
- Color-coded status codes (green for 2xx, yellow for 4xx, red for 5xx)
## ๐ง Error Handling
The service implements comprehensive error handling:
- **400 Bad Request**: Invalid input (e.g., invalid hex color codes)
- **404 Not Found**: Route not found
- **500 Internal Server Error**: Unexpected server errors
All errors are logged with full stack traces for debugging.
## ๐ Logging
The service provides detailed logging:
- **Request Logging**: Timestamp, HTTP method, and path
- **Response Logging**: Status code and response duration
- **Error Logging**: Full error messages and stack traces
- **Color-coded Output**: Green for success, yellow for warnings, red for errors
## ๐ Graceful Shutdown
The service handles termination signals properly:
- **SIGTERM**: Graceful shutdown on termination signal
- **SIGINT**: Graceful shutdown on interrupt signal (Ctrl+C)
- **Timeout**: Forces shutdown after 10 seconds if graceful shutdown fails
- **Cleanup**: Properly closes server connections
## ๐ค Contributing
We welcome contributions! Please read [CONTRIBUTION.md](./CONTRIBUTION.md) for details on:
- How to contribute
- Coding style guidelines
- Commit message conventions
- Code review process
## ๐ Author
## ๐ฅ Contributors
[](https://badges.pufler.dev)
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## ๐ Acknowledgments
1. [sagar-viradiya](https://github.com/sagar-viradiya/sagar-viradiya)
2. [pufler.dev/badge-it/](https://pufler.dev/badge-it/)
3. [github-readme-counter](https://github.com/iamskok/github-readme-counter)
## ๐ Additional Documentation
- [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) - Details on query parameter simplification
- [REFACTORING_SUMMARY.md](./REFACTORING_SUMMARY.md) - Complete refactoring documentation
- [SECURITY.md](./SECURITY.md) - Security policy and reporting
- [CONTRIBUTION.md](./CONTRIBUTION.md) - Contribution guidelines
## ๐ Show Your Support
If you find this project helpful, please consider:
- โญ Starring the repository
- ๐ด Forking and contributing
- ๐ข Sharing with others
---
Built with โค๏ธ using Express.js, following Clean Code principles and SOLID design patterns.
