Skip to content

pradyunL/CNAD_Assignment2

BranchesTags

Repository files navigation

CareConnect

A cloud-native mobile application designed for Persons with Intellectual Disabilities (PWIDs) and their Caretakers. Built with a microservices architecture, CareConnect helps PWIDs manage daily tasks (medication, meals, hygiene) with gamification-driven motivation, while giving caretakers real-time analytics and task management tools.

Architecture Overview

graph TD
    subgraph Client
        FE[Frontend - Port 8081]
    end

    subgraph Docker[Docker Compose Network]
        AUTH[Auth Service - 3001]
        TASK[Task Service - 3002]
        GAMIFY[Gamification Service - 3003]
        ANALYTICS[Analytics Service - 3004]
        GUIDE[Task Guide Service - 3005]
        DB[PostgreSQL - 5432]
    end

    subgraph AWS[AWS Cloud]
        REKOG[AWS Rekognition]
        S3[AWS S3]
    end

    FE --> AUTH
    FE --> TASK
    FE --> GAMIFY
    FE --> ANALYTICS
    FE --> GUIDE

    TASK --> GAMIFY

    AUTH --> DB
    TASK --> DB
    GAMIFY --> DB
    ANALYTICS --> DB
    GUIDE --> DB

    AUTH -.-> REKOG
    GUIDE -.-> S3
Loading

Service Communication

sequenceDiagram
    participant App
    participant Auth
    participant Task
    participant Gamify
    participant DB

    App->>Auth: Login request
    Auth->>DB: Verify credentials
    Auth-->>App: JWT token

    App->>Task: Complete task
    Task->>DB: Mark completed
    Task->>Gamify: Task completed event
    Note over Task,Gamify: 5s timeout with graceful degradation
    Gamify->>DB: Award points
    Gamify-->>Task: OK
    Task-->>App: Task completed

    App->>Gamify: Get rewards dashboard
    Gamify->>DB: Query points and level
    Gamify-->>App: Dashboard data
Loading

Database Schema

erDiagram
    users ||--o{ tasks : creates
    users ||--o{ caretaker_pwid : joins
    users ||--o{ user_achievements : earns
    users ||--o{ user_points : tracks
    users ||--o{ media : owns
    tasks ||--o{ task_schedules : generates
    achievements ||--o{ user_achievements : tracks
    levels ||--o{ user_points : determines

    users {
        int id
        varchar name
        varchar email
        varchar phone_number
        varchar password_hash
        varchar role
    }

    tasks {
        int id
        int pwid_id
        int caretaker_id
        varchar title
        varchar category
        time scheduled_time
        boolean is_recurring
    }

    task_schedules {
        int id
        int task_id
        date scheduled_date
        varchar status
        timestamp completed_at
    }

    achievements {
        int id
        varchar name
        varchar category
        int target_count
    }

    user_achievements {
        int id
        int user_id
        int achievement_id
        boolean is_earned
    }

    levels {
        int id
        int level_number
        varchar name
        int points_required
    }

    user_points {
        int id
        int user_id
        int total_points
        int current_level_id
    }

    caretaker_pwid {
        int id
        int caretaker_id
        int pwid_id
        varchar relationship
    }

    media {
        int user_id
        int location_id
        int media_id
        varchar media_type
    }
Loading

Services

Service Port Tech Description
Auth Service 3001 Express + TypeScript User registration, JWT login, biometric face login (AWS Rekognition), profile management, PIN change
Task Service 3002 Express + TypeScript Task CRUD, daily scheduling, completion tracking, caretaker-PWID relationship management
Gamification Service 3003 Express + TypeScript Points system, 10-tier leveling, 6 achievements, streak tracking
Analytics Service 3004 Express + TypeScript Caretaker dashboards, care recipient summaries, adaptation hints
Task Guide Service 3005 Express + TypeScript NFC tag-triggered media guides, AWS S3 upload/retrieval for images and videos
PostgreSQL 5432 PostgreSQL 16 Alpine Shared relational database with health checks
Frontend 8081 React Native (Expo) Cross-platform mobile app with i18n (EN/ZH), NFC scanning, push notifications

Key Features

For PWIDs:

  • Daily task dashboard with progress tracking
  • Task categories: medication, meals, hygiene
  • Completion celebrations with point rewards
  • Achievement system (Early Bird, Perfect Day, 7-Day Streak, etc.)
  • 10-level progression (Starter to Legend)
  • Card matching memory game
  • Push notification reminders
  • NFC tag scanning for video/image task guides
  • Bilingual support (English / Simplified Chinese)
  • Biometric face login (AWS Rekognition)

For Caretakers:

  • Create and manage tasks for assigned PWIDs
  • Real-time analytics dashboard with completion rates
  • Adaptation hints based on PWID performance
  • Upload task guide media (images/videos) via S3
  • Manage caretaker-PWID relationships

Cloud-Native Design

  • Containerized microservices -- each service has its own Dockerfile, independently deployable
  • Docker Compose orchestration -- single-command startup with health check dependencies
  • Kubernetes (EKS) deployment -- backend can be deployed to AWS EKS for container orchestration and cloud scalability; see Container Orchestration and Cloud Scalability (AWS EKS)
  • Health endpoints -- every service exposes /health for liveness probes
  • Graceful degradation -- task completion succeeds even if gamification service is unreachable (5s timeout with AbortController)
  • Connection pooling -- PostgreSQL pool (max 20 connections, 30s idle timeout)
  • Auto-restart -- restart: unless-stopped on all containers
  • CI/CD pipeline -- GitHub Actions: ESLint + TypeScript build + Docker integration test with health checks
  • Environment-driven config -- all secrets and endpoints configurable via .env variables

Prerequisites

Quick Start

1. Configure environment

cp .env.example .env
# Edit .env with your database credentials and AWS keys

2. Start backend services

docker compose up --build -d

This starts PostgreSQL, auth-service, task-service, gamification-service, analytics-service, and task-guide-service. The database is automatically initialized with schema and seed data.

3. Start the frontend

cd frontend
npm install
npm start
  • Press w for web browser (http://localhost:8081)
  • Scan QR code with Expo Go for mobile (same WiFi network)

4. Create an account

  1. Open the app and tap Create an account
  2. Fill in name, email, phone, 6-digit PIN, and role (PWID or Caretaker)
  3. Log in with your email and PIN

Environment Variables

Variable Description Default
DB_USER PostgreSQL username postgres
DB_PASSWORD PostgreSQL password postgres
DB_NAME Database name appdb
DB_PORT Database port 5432
JWT_SECRET JWT signing secret --
JWT_EXPIRES_IN Token expiry 7d
AWS_REGION AWS region for Rekognition/S3 --
AWS_ACCESS_KEY_ID AWS access key --
AWS_SECRET_ACCESS_KEY AWS secret key --
AWS_S3_BUCKET_NAME S3 bucket for media --
REKOGNITION_COLLECTION_ID Rekognition face collection careconnect-faces

API Endpoints

Auth Service (:3001/api/auth)

Method Endpoint Auth Description
POST /signup No Register new user
POST /login No Email + PIN login
POST /biometric-login No Face recognition login
POST /register-face JWT Register face for biometric login
GET /profile JWT Get user profile
PUT /profile JWT Update profile (name, email, phone)
PUT /change-pin JWT Change 6-digit PIN
GET /health No Health check

Task Service (:3002/api/tasks)

Method Endpoint Auth Description
GET /home JWT Home screen data (progress, tasks)
GET / JWT List all tasks
POST / JWT Create a task
GET /:id JWT Get task details
PUT /:id JWT Update a task
DELETE /:id JWT Delete a task
GET /schedule JWT Get daily schedule
POST /schedule/:id/complete JWT Mark schedule completed
POST /schedule/:id/uncomplete JWT Undo completion
GET /recent-completions JWT Recent activity feed

Task Service -- Caretaker Routes (:3002/api/caretaker)

Method Endpoint Auth Description
GET /pwids JWT (Caretaker) List assigned PWIDs
POST /pwids JWT (Caretaker) Add PWID relationship
GET /dashboard JWT (Caretaker) Caretaker dashboard
PUT /relationships/:id JWT (Caretaker) Update relationship
DELETE /relationships/:id JWT (Caretaker) Remove relationship
GET /my-caretakers JWT (PWID) View assigned caretakers

Gamification Service (:3003/api)

Method Endpoint Auth Description
GET /achievements JWT List all achievements with progress
POST /events/task-completed JWT Record task completion event
POST /events/task-uncompleted JWT Record task undo event
GET /rewards/dashboard JWT Points, level, achievements summary

Analytics Service (:3004/api/analytics)

Method Endpoint Auth Description
GET /care-recipients JWT (Caretaker) List care recipients
GET /care-recipients/:id/summary JWT (Caretaker) Detailed PWID analytics
GET /care-recipients/:id/adaptation-hints JWT (Caretaker) AI-driven care suggestions

Task Guide Service (:3005/api/S3)

Method Endpoint Auth Description
GET /:locationId JWT Get media for NFC location
POST /upload JWT Upload media to S3
DELETE /:mediaId JWT Delete media

Project Structure

CNAD_Assignment2/
├── .github/workflows/ci.yml          # CI pipeline (lint, build, Docker test)
├── docker-compose.yml                 # Service orchestration
├── .env.example                       # Environment template
│
├── frontend/                          # React Native (Expo) mobile app
│   ├── app/
│   │   ├── (auth)/                    # Login, signup screens
│   │   ├── (tabs)/                    # Home, tasks, rewards, profile, etc.
│   │   └── match-pairs.tsx            # Card matching game
│   ├── components/ui/                 # Reusable UI components
│   ├── contexts/                      # AuthContext, LanguageContext
│   ├── services/                      # i18n, notifications, auto-translate
│   ├── locales/                       # en.json, zh.json translations
│   └── utils/                         # NFC, S3 utilities
│
├── services/
│   ├── auth-service/                  # Authentication & user management
│   │   └── src/ (controllers, models, middleware, routes, services)
│   ├── task-service/                  # Task management & scheduling
│   │   └── src/ (controllers, models, middleware, routes)
│   ├── gamification-service/          # Points, levels, achievements
│   │   └── src/ (controllers, models, middleware, routes)
│   ├── analytics-service/             # Caretaker analytics
│   │   └── src/ (controllers, middleware, routes)
│   ├── task-guide-service/            # S3 media management
│   │   └── src/ (controllers, models, middleware, routes)
│   └── db-service/                    # Database schema & seed data
│       ├── db.sql                     # Schema definition
│       └── seed.sql                   # Test data

Stopping the App

# Stop all backend services
docker compose down

# Stop and wipe database
docker compose down -v

# Stop frontend: Ctrl+C in terminal

Troubleshooting

Services won't start:

docker compose logs              # View all logs
docker compose logs auth-service # View specific service

Reset database:

docker compose down -v
docker compose up --build -d
docker exec -i database_postgres psql -U postgres -d appdb < services/db-service/seed.sql

Check service health:

curl http://localhost:3001/api/auth/health
curl http://localhost:3002/health
curl http://localhost:3003/health
curl http://localhost:3004/health
curl http://localhost:3005/health

Container Orchestration and Cloud Scalability (AWS EKS)

CareConnect implements container orchestration and cloud scalability on cloud services by running the backend on Amazon EKS (Elastic Kubernetes Service). This satisfies the requirement for deployment and scaling in the cloud.

What this means

  • Container orchestration — Kubernetes (EKS) schedules, runs, and manages all backend containers (PostgreSQL and the five Node.js services). It handles service discovery, load balancing, restarts, and rolling updates.
  • Cloud scalability — The workload runs on AWS. The EKS node group can scale (e.g. from 1 to 3 nodes in cluster.yaml), and each microservice can be scaled independently (e.g. kubectl scale deployment auth-service -n careconnect --replicas=2).

How Kubernetes deployment works

  1. Cluster — An EKS cluster is created with eksctl; it runs in your AWS account and has a control plane plus a managed node group (EC2 instances that run your pods).
  2. Images — Each service is built as a Docker image, pushed to Amazon ECR, and referenced in Kubernetes Deployments.
  3. Manifests — The k8s/ directory contains Kubernetes manifests:
    • Namespace careconnect for isolation
    • ConfigMap and Secret for non-sensitive and sensitive configuration (DB, JWT, AWS keys)
    • PersistentVolumeClaim for PostgreSQL data (EBS via the EBS CSI driver)
    • Deployments for postgres and each app service (auth, task, gamification, analytics, task-guide)
    • Services — ClusterIP for internal traffic; LoadBalancer so each app gets a public URL for the mobile app
  4. Frontend — The Expo app runs on your machine or device (Expo Go). It talks to the backend using the LoadBalancer hostnames; you set these in frontend/.env as EXPO_PUBLIC_API_URL, etc.

The same codebase runs locally with Docker Compose or in the cloud on EKS; only the deployment target and API base URLs change.

High-level architecture on EKS

flowchart LR
  subgraph Client
    App[Expo app]
  end
  subgraph AWS_EKS[AWS EKS]
    subgraph careconnect[Namespace careconnect]
      LB_A[LoadBalancer :3001]
      LB_T[LoadBalancer :3002]
      LB_G[LoadBalancer :3003]
      LB_AN[LoadBalancer :3004]
      LB_S[LoadBalancer :3005]
      AUTH_P[auth-service]
      TASK_P[task-service]
      GAMIFY_P[gamification-service]
      ANALYTICS_P[analytics-service]
      GUIDE_P[task-guide-service]
      DB_P[postgres]
    end
  end
  App --> LB_A
  App --> LB_T
  App --> LB_G
  App --> LB_AN
  App --> LB_S
  LB_A --> AUTH_P
  LB_T --> TASK_P
  LB_G --> GAMIFY_P
  LB_AN --> ANALYTICS_P
  LB_S --> GUIDE_P
  AUTH_P --> DB_P
  TASK_P --> DB_P
  GAMIFY_P --> DB_P
  ANALYTICS_P --> DB_P
  GUIDE_P --> DB_P
Loading

Deploying to AWS EKS (steps)

  1. Install — AWS CLI, Docker, kubectl, eksctl. Run aws configure with your AWS credentials (use an IAM user with EKS/ECR/EC2 permissions).
  2. Create cluster (one-time, ~15–20 min) — From the project root: 
    eksctl create cluster -f cluster.yaml
    If kubectl later reports "aws not found" or "aws-iam-authenticator not found", run: 
    aws eks update-kubeconfig --region us-east-1 --name careconnect
  3. EBS CSI driver (for PostgreSQL volume) — If the cluster does not already have the EBS CSI addon and IAM permissions, create the addon and attach the EBS policy to the node role so the postgres-data PVC can bind. See k8s/README.md for details.
  4. Secrets — In the project root .env, set DB_PASSWORD, JWT_SECRET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (and optionally AWS_S3_BUCKET_NAME). The deploy script creates the Kubernetes secret from this file.
  5. Deploy — From the project root:
    • Windows: .\scripts\deploy-eks.ps1
    • Mac/Linux/WSL: ./scripts/deploy-eks.sh The script creates ECR repos, builds and pushes the five service images, updates k8s/ with your AWS account and region, creates the secret, and applies all manifests.
  6. Frontend URLs — After 2–3 minutes, run kubectl get svc -n careconnect and set EXPO_PUBLIC_API_URL, EXPO_PUBLIC_TASK_API_URL, EXPO_PUBLIC_GAMIFICATION_API_URL, EXPO_PUBLIC_ANALYTICS_API_URL, and EXPO_PUBLIC_S3_API_URL in frontend/.env to the LoadBalancer hostnames (ports 3001–3005). Then start the frontend (cd frontend && npm start) and use Expo Go as usual.

Full step-by-step instructions, apply order, and troubleshooting (e.g. PVC binding, postgres init) are in k8s/README.md.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages