Forecast API

A robust Node.js API built with TypeScript, following a Modular Monolith architecture and Clean Code principles. This API fetches weather data from external services (StormGlass), processes it, and provides surf forecasts for registered beaches.

🚀 Features

• Modular Monolith Architecture: Organized by domain modules (users, beaches, forecast) for better maintainability and scalability.
• User Management: Registration, authentication (JWT), and profile management.
• Beach Management: Create and manage favorite beaches.
• Surf Forecast: Fetch and process wave/wind data to rate surf conditions.
• Security:
  • JWT Authentication
  • Rate Limiting
  • Security Headers (Helmet)
  • Password Hashing (Bcrypt)
• Robustness:
  • Centralized Error Handling
  • Structured Logging (Pino)
  • Validation (Mongoose & OpenApiValidator)
• Production Ready:
  • Docker & Docker Compose support
  • GitHuB Actions CI pipeline

🛠️ Tech Stack

• Runtime: Node.js (v20+)
• Language: TypeScript
• Framework: Express.js
• Database: MongoDB (Mongoose v8)
• Testing: Jest (Unit & Functional), Supertest, MongoDB Memory Server
• Documentation: OpenAPI (Swagger)
• Tooling: pnpm, ESLint, Prettier

📂 Project Structure

src/
  modules/          # Domain modules
    users/          # Users domain (Auth, Profile)
    beaches/        # Beaches domain (CRUD)
    forecast/       # Forecast domain (Logic, Rating)
  shared/
    core/           # Shared base classes/types
    infra/          # Infrastructure (Database, HTTP)
  util/             # Utilities (Logger, Errors)
  clients/          # External API clients

⚡ Getting Started

Prerequisites

• Node.js v20+
• pnpm
• MongoDB (locally or via Docker)

Installation

1. Clone the repository:

   git clone <repo-url>
   cd forecast-api

2. Install dependencies:

   pnpm install

3. Configure environment variables: Copy .env.example to .env (if applicable) or rely on config/default.json.

Running Locally

Development mode with hot reload:

pnpm start:local

The API will be available at http://localhost:3000. Documentation (Swagger) available at http://localhost:3000/docs.

Running with Docker

1. Build and run the containers:

   docker-compose up --build

This will start the API and a MongoDB instance.

🧪 Testing

The project includes a comprehensive test suite.

Run Unit Tests:

pnpm test:unit

Run Functional (E2E) Tests: These tests run against an in-memory MongoDB instance for isolation.

pnpm test:functional

🔨 Build

To compile the TypeScript code for production:

pnpm build

🤝 Contributing

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request