Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Sufianeh7/AmigoInvisible/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running the complete Amigo Invisible stack on your local machine. By the end you will have the Node.js/Express API connected to MongoDB, the Angular SPA served on localhost:4200, and everything wired together so you can create a group and trigger a real Secret Santa draw with emails going out.

​
Prerequisites

Make sure the following are available on your machine before you start:
  • Node.js 18+ and npm — verify with node -v and npm -v.
  • Angular CLI — install globally if you do not already have it: 
    npm install -g @angular/cli
  • MongoDB connection string — either a free MongoDB Atlas cluster or a locally running MongoDB instance.
  • Gmail account with an App Password — standard Gmail passwords will not work; see the tip at the bottom of this page.

​
Clone the Repository

git clone https://github.com/Sufianeh7/AmigoInvisible.git
cd AmigoInvisible

​
Setup Steps

1

Configure the Backend

Create a .env file inside the Node/ directory. The server reads these four variables at startup via dotenv:
Node/.env
MONGO_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/amigoInvisible
EMAIL_USER=your.email@gmail.com
EMAIL_PASS=your_gmail_app_password
PORT=3000
VariablePurpose
MONGO_URIFull MongoDB connection string including database name
EMAIL_USERThe Gmail address Nodemailer will send from
EMAIL_PASSA Gmail App Password (not your regular Gmail password)
PORTThe port Express will listen on (defaults to 3000)
2

Start the Backend

Open a terminal, navigate to the Node/ directory, install dependencies, and start the development server:
cd Node
npm install
npm run dev
npm run dev uses nodemon so the server restarts automatically on any file change. You should see both of these lines in the console before continuing:
✅ Conectado a MongoDB
Servidor corriendo en el puerto 3000
If you see ❌ Error al conectar a MongoDB, double-check your MONGO_URI value and that your Atlas cluster allows connections from your IP address.
3

Start the Frontend

Open a new terminal (keep the backend running), navigate to the Angular/ directory, install dependencies, and start the dev server:
cd Angular
npm install
npm start
npm start runs ng serve. Once compilation finishes, open your browser and navigate to:
http://localhost:4200
You should see the group-creation form. The Angular app is pre-configured to call the production backend URL in GrupoService. To point it at your local backend instead, open Angular/src/app/servicios/grupo.ts and change apiUrl to http://localhost:3000/api/sorteos.
4

Create Your First Group

With both servers running, use the form at http://localhost:4200 to create a test draw:
  1. Enter a group name (e.g., “Office Party 2025”).
  2. Optionally set a budget.
  3. Add at least 3 participants, each with a name and a valid email address. You can add exclusions to any participant by listing the names of people they must not give a gift to.
  4. Click Create Group. The backend generates a UUID adminToken and redirects you to /sorteo/:adminToken.
  5. On the admin page, review the participant list, then click Launch Draw. The algorithm runs, updates the draw status to completado, and immediately sends an individual email to each participant.
Check the inboxes you used — each participant will receive an HTML email from the configured EMAIL_USER address revealing only their own assignment.
Setting up a Gmail App Password: Regular Gmail passwords are rejected by Google’s SMTP server when used from third-party apps. To generate an App Password:
  1. Go to your Google Account → Security.
  2. Under “How you sign in to Google”, enable 2-Step Verification if it is not already on.
  3. Search for App Passwords in the Security settings search bar.
  4. Choose “Mail” as the app, select your device type, and click Generate.
  5. Copy the 16-character password into your Node/.env as EMAIL_PASS.
Your adminToken URL (e.g., http://localhost:4200/sorteo/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) is the only way to access the group management page. There is no account system and no password-recovery flow. Bookmark it immediately after creating a group — if the URL is lost, there is no way to retrieve it.

Build docs developers (and LLMs) love

Get started for freeTalk to us