🧭 Compass Events API

---

📑 Table of Contents

• Description
• Main Features
• Technologies
• Prerequisites
• Environment Variables
• How to Run
• API Endpoints
• Authentication
• Folder Structure
• Testing
• Contribution
• Author

---

📘 Description

The Compass Events API is a RESTful application for managing events, user registration, and event subscriptions.

Built with NestJS and TypeScript, it uses AWS DynamoDB for storage, AWS S3 for file uploads, and AWS SES for email notifications (including iCalendar attachments).

---

🧩 Main Features

• User registration & authentication (JWT)
• Event management (create, edit, list, soft delete)
• Event subscription with iCalendar (.ics) e-mail notification
• Profile & event image upload to AWS S3
• E-mail notifications via AWS SES
• Admin, organizer, and participant roles
• API documentation with Swagger
• Tests with jest

---

💻 Technologies

• Backend: NestJS, TypeScript
• Database: AWS DynamoDB
• File Storage: AWS S3
• E-mail: AWS SES
• Documentation: Swagger (OpenAPI)

---

📋 Prerequisites

• Node.js v18 or higher
• npm
• AWS account (for S3, SES, DynamoDB)
• AWS credentials set in .env

---

⚙️ Environment Variables

Create a .env file in the project root. Example:

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_SESSION_TOKEN=your-session-token
AWS_REGION=us-east-1

JWT_SECRET=your-jwt-secret

AWS_S3_BUCKET=your-s3-bucket-name
PROFILE_IMAGE_DEFAULT=https://your-bucket.s3.amazonaws.com/profile/default.jpg
IMAGE_DEFAULT=https://your-bucket.s3.amazonaws.com/images/default.jpg

PORT=3000

SEED_DEFAULT_USER_NAME=AdminName
SEED_DEFAULT_USER_EMAIL=admin@example.com # Use a verified Email for AWS SES
SEED_DEFAULT_USER_PASSWORD=AdminPassword123
SEED_DEFAULT_USER_PHONE=+5511999999999
SEED_DEFAULT_USER_ROLE=admin

AWS_SES_FROM=your-verified-email@example.com

BASE_URL=http://localhost:3000

---

🚀 How to Run the Project

1. Clone the repository:

   git clone https://github.com/your-username/ANMAR25_D03_COMPASSEVENT.git
   cd ANMAR25_D03_COMPASSEVENT

2. Install dependencies:

   npm install

3. Configure environment variables:

   • Copy .env.example to .env and fill in your AWS credentials and other required variables.

4. Run the application:

   • Development:

     npm run dev

   • Production:

     npm run build
     npm run start:prod

5. Access the API documentation:

   • Open http://localhost:3000/docs in your browser for Swagger UI.

6. Seed the default admin user (optional):

   npm run seed

7. Run tests:

   npm run test
   npm run test:cov

---

📚 API Endpoints

Auth

• POST /auth/login — User login
• POST /auth/register — User registration
• GET /auth/me — Get current user info (JWT required)
• GET /auth/verify-email — Verify user e-mail

Users

• POST /user — Create user
• PATCH /user/:id — Update user
• GET /user — List users (admin only)
• GET /user/:id — Get user by ID
• DELETE /user/:id — Soft delete user

Events

• POST /event — Create event (admin/organizer only)
• PATCH /event/:id — Update event (admin/organizer only)
• GET /event — List events
• GET /event/:id — Get event by ID
• DELETE /event/:id — Soft delete event (admin/organizer only)

Subscriptions

• POST /subscription/:eventId — Subscribe to event (sends .ics)
• GET /subscription — List subscriptions
• DELETE /subscription/:eventId — Cancel subscription

---

🛡️ Authentication

• All private endpoints require a JWT token in the Authorization header as a Bearer token.
• Roles: admin, organizer, participant.
• Use /auth/login to obtain your token.

---

📧 Email Notifications

Compass Events API uses AWS SES to automatically send emails in several scenarios:

• Email verification: After registration, users receive a link to verify their email address.
• Event notifications: Organizers and participants are notified by email when events are created or deleted.
• Event subscription: When subscribing to an event, participants receive an email with an iCalendar (.ics) file attached, so they can add the event to their calendar.
• Unsubscription and account deletion: Users are notified by email when they unsubscribe from an event or delete their account.

All emails are sent via the AWS SES SDK. If AWS credentials are not set in the .env file, email sending is automatically skipped.

---

☁️ AWS S3 File Storage

The project uses AWS S3 to store user profile images and event images:

• Profile images: Saved in the profile/ folder of your S3 bucket.
• Event images: Saved in the events/ folder of your S3 bucket.

Uploads happen automatically when creating or updating users/events with images. The public URL of each image is stored in the database and returned in API responses.

---

📁 Folder Structure

src/
│
├── auth/           # Authentication and authorization
├── common/         # Guards, decorators, enums
├── dynamodb/       # DynamoDB client and module
├── event/          # Event module
├── models/         # Data models
├── s3/             # S3 upload service
├── ses/            # SES e-mail service
├── subscription/   # Subscription module
├── user/           # User module
└── main.ts         # Application entry point

---

Commits and Prs

• Semantic commits (feat:, fix:, docs:)
• Pull Requests (PRs) with a clear description of changes.

---

👤 Author

This project was created by Thiago Sampaio

📎 Useful Links

• NestJS Docs
• AWS SES Docs
• AWS DynamoDB Docs
• ical-generator
• Swagger