This guide will help you get AICA (AI Communication Assistant) running on your local machine.

Make sure you have the following installed:

• Node.js (v18 or higher recommended)
• npm (comes with Node.js)
• MongoDB (local installation) or MongoDB Atlas (cloud database)

You will also need accounts for:

• Auth0 (for authentication)
• OpenAI (for AI-powered email generation)
• Microsoft Azure (for Outlook integration - optional)

Optional but recommended:

• A code editor such as VS Code
• MongoDB Compass (GUI for MongoDB)

Open your terminal and clone the project:

git clone https://github.com/Etown-CS170/2025-AICA.git

Navigate into the project folder:

cd 2025-AICA

From the root directory:

npm run install:all

Backend Dependencies:

cd backend
npm install

Frontend Dependencies:

cd ../frontend
npm install

Root Dependencies:

cd ..
npm install

1. Install MongoDB Community Server
2. Start MongoDB:

 # macOS/Linux
 sudo systemctl start mongod
 
 # Or use MongoDB Compass to start the server

3. Your MongoDB URI will be: mongodb://localhost:27017/aica

1. Create a free account at MongoDB Atlas
2. Create a new cluster
3. Click "Connect" and choose "Connect your application"
4. Copy your connection string (it will look like):

 mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/aica?retryWrites=true&w=majority

5. Replace <username> and <password> with your database credentials

1. Create an account at Auth0
2. Create a new Single Page Application in your Auth0 Dashboard
3. Configure the following settings:
   • Allowed Callback URLs: http://localhost:4200
   • Allowed Logout URLs: http://localhost:4200
   • Allowed Web Origins: http://localhost:4200
4. Create a new API in your Auth0 Dashboard:
   • Identifier: https://aica-backend-api
   • Signing Algorithm: RS256
5. Note your Domain and Client ID from the application settings

If you want to enable Outlook email sending capabilities:

1. Go to the Azure Portal
2. Navigate to Azure Active Directory → App registrations → New registration
3. Configure your app:
   • Name: AICA Outlook Integration
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI:
     • Platform: Single-page application (SPA)
     • URI: http://localhost:4200/outlook/callback
4. After registration, note your Application (client) ID
5. Go to Certificates & secrets → New client secret:
   • Description: AICA Backend Secret
   • Expiration: Choose appropriate duration
   • Copy the secret value immediately (it won't be shown again)
6. Go to API permissions → Add a permission → Microsoft Graph:
   • Add Delegated permissions:
     • Mail.Send
     • Mail.Read
     • User.Read
     • offline_access
   • Click Grant admin consent (if you have admin rights)
7. Note your Directory (tenant) ID from the Overview page

In the backend folder, create a .env file:

cd backend
touch .env

Add the following variables:

# Server Configuration
PORT=3000
NODE_ENV=development
CORS_ORIGIN=http://localhost:4200
# Auth0 Configuration
AUTH0_DOMAIN=your-auth0-domain.auth0.com
AUTH0_AUDIENCE=https://aica-backend-api
# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017/aica
# Or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/aica?retryWrites=true&w=majority
# Microsoft Outlook Configuration (Optional)
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_REDIRECT_URI=http://localhost:4200/outlook/callback

Important:

• Replace your-auth0-domain with your actual Auth0 domain
• Replace sk-your-openai-api-key-here with your OpenAI API key from the OpenAI Dashboard
• Update MONGODB_URI with your MongoDB connection string
• Replace your-microsoft-client-id with your Azure Application (client) ID
• Replace your-microsoft-client-secret with your Azure client secret value

In the frontend/src/environments folder, update environment.ts:

export const environment = {
 production: false,
 apiUrl: 'http://localhost:3000/api',
 auth0: {
 domain: 'your-auth0-domain.auth0.com',
 clientId: 'your-auth0-client-id',
 authorizationParams: {
 redirect_uri: window.location.origin,
 audience: 'https://aica-backend-api'
 },
 cacheLocation: 'localstorage' as const,
 useRefreshTokens: true
 },
 microsoft: {
 clientId: 'your-microsoft-client-id',
 redirectUri: 'http://localhost:4200/outlook/callback',
 tenantId: 'common'
 }
};

Important:

• Replace your-auth0-domain and your-auth0-client-id with your actual Auth0 credentials
• Replace your-microsoft-client-id with your Azure Application (client) ID

From the root directory:

npm run dev

This will start both the backend and frontend servers concurrently.

Terminal 1 - Backend Server:

cd backend
npm run dev

You should see:

✅ MongoDB connected successfully
🚀 AICA Backend Server running on port 3000
📧 Environment: development

Terminal 2 - Frontend Application:

cd frontend
npm start

The app will be accessible at http://localhost:4200 in your browser.

1. Open your browser and navigate to http://localhost:4200
2. Click Sign In to authenticate with Auth0
3. Choose your authentication method (Google, Microsoft, GitHub, Apple, or email/password)
4. Once authenticated, you can:
   • Select a tone (Professional, Friendly, Formal, Persuasive) or create a custom tone
   • Select an audience (Professor, Student, Coach, Professional) or specify a custom audience
   • Choose from quick templates or describe your email needs
   • Add custom email signatures
   • Generate professional emails powered by OpenAI GPT-4o-mini
   • Save generated emails to your library
   • Connect Outlook (if configured) to send emails directly through your Outlook account
   • Manage all preferences in the Settings modal

If you encounter issues:

1. Check Console Logs - Review backend terminal and browser console for error messages
2. Verify Configuration - Ensure all environment variables match the required format
3. Check Versions - Verify Node.js v18+ is installed (node --version)
4. Database Connection - Confirm MongoDB is running and accessible
5. Clean Install - Clear and reinstall dependencies:

 npm run install:all

6. Port Check - Ensure servers run on correct ports (backend: 3000, frontend: 4200)
7. Auth0 Setup - Double-check Auth0 configuration including callback URLs and API audience
8. Microsoft Setup - Verify Azure app registration, client ID, client secret, and redirect URI

npm run dev # Start backend with hot reload (nodemon)
npm run build # Compile TypeScript to JavaScript
npm start # Start production server (requires build first)

npm start # Start development server with hot reload
ng serve # Alternative to npm start
ng build # Build for production
ng test # Run unit tests with Karma

npm run dev # Start both servers concurrently ✨ Recommended
npm run dev:backend # Start only backend server
npm run dev:frontend # Start only frontend server
npm run install:all # Install all dependencies (root, backend, frontend)

Using MongoDB Compass:

1. Open MongoDB Compass
2. Connect to mongodb://localhost:27017 (or your Atlas URI)
3. Select the aica database
4. Browse the userpreferences and outlooktokens collections

Using MongoDB Shell:

mongosh
use aica
db.userpreferences.find().pretty()
db.outlooktokens.find().pretty()

Via MongoDB Shell:

use aica
db.userpreferences.deleteMany({}) // Clear all user preferences
db.outlooktokens.deleteMany({}) // Clear all Outlook connections

Via Application:

• Use the "Reset to Defaults" button in Settings modal (preserves authentication)
• Use the "Disconnect" button in Outlook Integration section to remove Outlook connection