OneST - Singapore Services Portal

OneST is a modern web portal that provides multiple services to the public, specifically designed for Singapore. The platform offers UEN (Unique Entity Number) validation and real-time weather forecast services through a clean, responsive interface.

🌟 Features

UEN Validation Service

✅ Validates all three official UEN formats (A, B, C)
🏢 Entity type identification and mapping
📋 Comprehensive format examples and help
⚡ Real-time client-side and server-side validation
📱 Mobile-responsive interface

Weather Forecast Service

🌤️ Real-time 2-hour weather forecasts
📍 Location-specific forecasts for all Singapore areas
🔄 Auto-refresh with caching
🗺️ Geographic coordinates for forecast areas
📊 Data from official Singapore Government APIs

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│                 │    │                  │    │                 │
│   React + Vite  │◄──►│   Next.js API    │◄──►│  External APIs  │
│    Frontend     │    │     Backend      │    │  (Weather Data) │
│   (Port 3000)   │    │   (Port 3001)    │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Technology Stack

Frontend:

React 18+ with functional components and hooks
Vite for fast development and optimized builds
Tailwind CSS for modern, responsive styling
Axios for HTTP requests
React Router for navigation
Lucide React for icons

Backend:

Next.js 13+ with App Router
RESTful API design
Built-in rate limiting and security headers
Comprehensive error handling
External API integration with fallback mechanisms

📋 Prerequisites

Before running this project, make sure you have the following installed:

Node.js (version 18.0 or higher)
npm (version 8.0 or higher)
Git (for cloning the repository)

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd onest-portal

2. Install Dependencies

Install dependencies for both frontend and backend:

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

3. Environment Configuration

Backend Configuration:

cd backend
cp .env.local.example .env.local
# Edit .env.local if needed (default values work for development)

Frontend Configuration: No additional environment configuration needed for development.

4. Start the Development Servers

Terminal 1 - Start Backend (Next.js API):

cd backend
npm run dev

The backend API will be available at http://localhost:3001

Terminal 2 - Start Frontend (React + Vite):

cd frontend
npm run dev

The frontend will be available at http://localhost:3000

5. Access the Application

Open your browser and navigate to:

Frontend: http://localhost:3000
Backend API: http://localhost:3001/api/health

📁 Project Structure

onest-portal/
├── backend/                 # Next.js Backend API
│   ├── lib/                # Business logic and utilities
│   │   ├── uen-validator.js    # UEN validation logic
│   │   ├── weather-client.js   # Weather API client
│   │   └── error-handler.js    # Error handling utilities
│   ├── pages/api/          # API routes
│   │   ├── uen/
│   │   │   ├── validate.js     # UEN validation endpoint
│   │   │   └── formats.js      # UEN format information
│   │   ├── weather/
│   │   │   ├── forecast.js     # Weather forecast endpoint
│   │   │   └── locations.js    # Available locations
│   │   └── health.js           # Health check endpoint
│   ├── middleware.js       # Rate limiting and CORS
│   ├── package.json
│   └── next.config.js
├── frontend/               # React + Vite Frontend
│   ├── src/
│   │   ├── components/     # Reusable React components
│   │   │   ├── Header.jsx
│   │   │   ├── Footer.jsx
│   │   │   ├── Layout.jsx
│   │   │   └── LoadingSpinner.jsx
│   │   ├── pages/          # Page components
│   │   │   ├── HomePage.jsx
│   │   │   ├── UENValidationPage.jsx
│   │   │   ├── WeatherPage.jsx
│   │   │   └── NotFoundPage.jsx
│   │   ├── services/       # API service layer
│   │   │   └── api.js
│   │   ├── App.jsx         # Main App component
│   │   └── main.jsx        # Entry point
│   ├── package.json
│   └── vite.config.js
├── docs/                   # Documentation
│   ├── REQUIREMENTS.md     # Detailed requirements
│   ├── DESIGN.md          # System design and architecture
│   └── TESTING.md         # Testing documentation
└── README.md              # This file

🔌 API Endpoints

UEN Validation

Validate UEN

GET /api/uen/validate?uen={uen}

Example:

curl "http://localhost:3001/api/uen/validate?uen=12345678A"

Response:

{
  "success": true,
  "data": {
    "uen": "12345678A",
    "isValid": true,
    "format": "A",
    "formatDescription": "Businesses registered with ACRA",
    "entityType": null,
    "details": {
      "length": 9,
      "pattern": "nnnnnnnX"
    }
  }
}

Get UEN Formats

GET /api/uen/formats

Weather Forecast

Get Weather Forecast

GET /api/weather/forecast?location={location}

Examples:

# All Singapore
curl "http://localhost:3001/api/weather/forecast"

# Specific location
curl "http://localhost:3001/api/weather/forecast?location=Ang%20Mo%20Kio"

Get Available Locations

GET /api/weather/locations

System Health

Health Check

GET /api/health

🧪 Testing

Backend Tests

cd backend
npm test                 # Run all tests
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Run tests with coverage report

Frontend Tests

cd frontend
npm test                 # Run all tests
npm run test:ui         # Run tests with UI
npm run test:coverage   # Run tests with coverage report

Manual Testing

UEN Validation:
- Test Format A: 12345678A
- Test Format B: 200912345A
- Test Format C: T09LL0001B
- Test invalid formats: invalid, 123, ABCDEFGHI
Weather Forecast:
- Test all Singapore forecast
- Test specific locations (Ang Mo Kio, Bedok, etc.)
- Test invalid locations
- Test refresh functionality

🚢 Production Deployment

Build for Production

Backend:

cd backend
npm run build
npm start

Frontend:

cd frontend
npm run build
npm run preview  # Preview production build locally

Environment Variables (Production)

Backend (.env.local):

NODE_ENV=production
API_PORT=3001
WEATHER_API_TIMEOUT=10000
WEATHER_CACHE_DURATION=300000
CORS_ORIGIN=https://your-frontend-domain.com

Deployment Options

Vercel (Recommended for Next.js)
- Deploy backend to Vercel
- Configure environment variables
- Set up custom domains
Netlify (For Frontend)
- Build and deploy frontend static files
- Configure redirects for SPA routing
Docker
- Create Dockerfiles for both services
- Use docker-compose for local development
- Deploy to container platforms
Traditional Hosting
- Use PM2 for process management
- Set up reverse proxy with Nginx
- Configure SSL certificates

🔧 Configuration

Backend Configuration

The backend can be configured through environment variables:

Variable	Default	Description
`NODE_ENV`	`development`	Environment mode
`API_PORT`	`3001`	Backend server port
`WEATHER_API_TIMEOUT`	`10000`	Weather API timeout (ms)
`WEATHER_CACHE_DURATION`	`300000`	Cache duration (ms)
`CORS_ORIGIN`	`*`	CORS allowed origin

Frontend Configuration

The frontend is configured through vite.config.js:

Proxy: API requests are proxied to backend during development
Build: Optimized production builds with source maps
Testing: Vitest configuration for unit tests

🐛 Troubleshooting

Common Issues

Port Already in Use

# Kill process using port 3000 or 3001
npx kill-port 3000
npx kill-port 3001

API Connection Issues
- Ensure backend is running on port 3001
- Check firewall settings
- Verify proxy configuration in vite.config.js
Weather API Failures
- Weather APIs may be temporarily unavailable
- Check network connectivity
- Review error messages in browser console

Build Issues

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Debug Mode

Enable detailed logging:

Backend:

NODE_ENV=development npm run dev

Frontend:

npm run dev

Check browser developer tools for detailed error messages and network requests.

📚 Additional Documentation

Requirements Specification - Detailed functional and non-functional requirements
System Design - Architecture, component design, and technical specifications
Testing Documentation - Testing strategy, test cases, and coverage requirements

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style and conventions
Write tests for new features
Update documentation as needed
Ensure all tests pass before submitting PR
Use meaningful commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

If you encounter any issues or have questions:

Check the troubleshooting section above
Review the additional documentation
Check existing GitHub issues
Create a new issue with detailed information

🎯 Future Enhancements

User authentication and personalization
Additional Singapore government services
Mobile app development
Advanced weather visualization
API rate limiting dashboard
Multi-language support
Dark mode theme
Progressive Web App (PWA) features

Built with ❤️ for Singapore 🇸🇬

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.gitignore		.gitignore
DESIGN.md		DESIGN.md
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
TESTING.md		TESTING.md
logo1.png		logo1.png
logo2.png		logo2.png
logo3.png		logo3.png
logo4.png		logo4.png
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

OneST - Singapore Services Portal

🌟 Features

UEN Validation Service

Weather Forecast Service

🏗️ Architecture

Technology Stack

📋 Prerequisites

🚀 Quick Start

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

4. Start the Development Servers

5. Access the Application

📁 Project Structure

🔌 API Endpoints

UEN Validation

Validate UEN

Get UEN Formats

Weather Forecast

Get Weather Forecast

Get Available Locations

System Health

Health Check

🧪 Testing

Backend Tests

Frontend Tests

Manual Testing

🚢 Production Deployment

Build for Production

Environment Variables (Production)

Deployment Options

🔧 Configuration

Backend Configuration

Frontend Configuration

🐛 Troubleshooting

Common Issues

Debug Mode

📚 Additional Documentation

🤝 Contributing

Development Guidelines

📄 License

🙋‍♂️ Support

🎯 Future Enhancements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages