NIMBUS — Secure AI-Powered University & Club Information Assistant
NIMBUS is an AI-powered Student & Club Member Portal that combines secure AWS Cognito authentication with Amazon Bedrock RAG to provide reliable, document-grounded answers to university and club-related queries. It stores conversation history in DynamoDB and provides a responsive PWA interface with source citations, secure APIs, and intelligent fallback handling.
⚡ NIMBUS Student & Club Member Portal
NIMBUS is an enterprise-grade AI-powered Student & Club Member Portal built on AWS Serverless architecture and Amazon Bedrock Retrieval-Augmented Generation (RAG). It provides intelligent, grounded answers to university and club member queries backed by verified knowledge base documents stored in S3, while maintaining session history, secure PKCE authentication via AWS Cognito, and instant responses via API Gateway and Lambda.
📋 Table of Contents
- High-Level Design (HLD)
- Low-Level Design (LLD)
- System Architecture & Workflow
- Key Features & Highlights
- Git Branching & Workflow Strategy
- API Contracts & JSON Examples
- Database Schema & Platform ID Design
- Production Database Migrations
- GitHub Actions CI/CD Pipeline & Secrets
- Security & Production Hardening
- Troubleshooting & Diagnostic Matrix
- Deployment Rollbacks & Log Auditing
- Local Setup Guide (NPM)
🏗 High-Level Design (HLD)
The High-Level Design showcases the global system architecture, client interfaces, authentication boundary, API Gateway route layer, serverless compute, Amazon Bedrock Knowledge Base RAG pipeline, and DynamoDB persistent storage.
🔍 Low-Level Design (LLD)
The Low-Level Design details the end-to-end component interaction sequence during an authenticated user session, query submission, RAG document retrieval, fallback evaluation, citation parsing, and state persistence.
⚙ System Architecture & Workflow
- Single Page Application (SPA) & PWA: Built with Vite, React 18, and Tailwind CSS. Features full Progressive Web App (PWA) manifest support for offline fallback cards and home screen installation.
- Identity & Access Management: Fully integrated with AWS Cognito User Pools. Supports user registration, email verification code flows, password reset, and session storage.
- API Routing: AWS API Gateway REST API with CORS enabled and Amazon Cognito Authorizer protecting private endpoints.
- Retrieval-Augmented Generation (RAG): Amazon Bedrock Knowledge Base ingests markdown/PDF documentation from S3 buckets. Upon receiving a member prompt, Bedrock performs semantic vector search over document chunks and constructs a grounded prompt for LLM inference.
- Session & History Storage: Chat history is persisted in Amazon DynamoDB with single-table design (
nimbus_chat_history), enabling member chat state restoration across devices.
✨ Key Features & Highlights
- Authenticated Chat Assistant: Interactive AI assistant restricted to authenticated club members.
- Dynamic Source Citations: Extracts exact document names, sections, and snippets from Bedrock citations for full transparency.
- Graceful Fallback Handling: Automatically detects low-confidence responses and presents official club officer contact information.
- Chat History Synchronization: Instant retrieval of historical conversations via
GET /chat/history.
- Responsive Dark/Light Glassmorphism UI: Built with modern Tailwind CSS aesthetics, responsive sidebar layout, and micro-animations.
- PWA Ready: Offline support banner and install prompt for desktop and mobile devices.
🌿 Git Branching & Workflow Strategy
NIMBUS follows a feature-branch workflow model for development, review, and deployment:
Branch Names & Rules
-
main: Production-ready branch. Pushing tomaintriggers automatic deployment to AWS Amplify and production Railway instances.
-
develop: Staging and integration branch.
-
feature/*: Dedicated feature development branches (e.g.,feature/chat-history,feature/pwa-install).
-
fix/*: Bug fixes and patch branches.
-
chore/*: Maintenance, dependency updates, and git hygiene.
🔌 API Contracts & JSON Examples
1. Send Question ( POST /chat )
Request Headers
POST /chat HTTP/1.1Host: <api-gateway-endpoint>Content-Type: application/jsonAuthorization: Bearer eyJraWQiOiJ... (AWS Cognito JWT ID/Access Token)Request Payload
{ "question": "What are the rules regarding project submission deadlines?"}Success Response ( 200 OK )
{ "conversationId": "conv_9823471029", "answer": "Project submissions must be finalized and uploaded to the official portal no later than 11:59 PM EST on the designated submission date. Late entries will incur a 10% point reduction per hour.", "sources": [ { "file": "03-builder-center-publish.md", "section": "Submission Guidelines", "snippet": "All submissions must be uploaded prior to 11:59 PM EST..." } ], "is_fallback": false, "timestamp": "2026-08-13T10:15:00Z"}Fallback Response ( 200 OK )
{ "conversationId": "conv_9823471030", "answer": "", "sources": [], "is_fallback": true, "timestamp": "2026-08-13T10:16:00Z"}
2. Fetch Chat History ( GET /chat/history )
Request Headers
GET /chat/history HTTP/1.1Host: <api-gateway-endpoint>Authorization: Bearer eyJraWQiOiJ...Success Response ( 200 OK )
{ "history": [ { "conversationId": "conv_9823471029", "sender": "user", "message": "What are the rules regarding project submission deadlines?", "timestamp": "2026-08-13T10:15:00Z" }, { "conversationId": "conv_9823471029", "sender": "assistant", "message": "Project submissions must be finalized and uploaded...", "sources": [ { "file": "03-builder-center-publish.md", "section": "Submission Guidelines", "snippet": "All submissions must be uploaded..." } ], "metadata": { "is_fallback": false }, "timestamp": "2026-08-13T10:15:02Z" } ]}
🗄 Database Schema & Platform ID Design
DynamoDB Table: nimbus_chat_history
Attribute Name | Data Type | Key Type | Description |
|---|---|---|---|
userId | String (S) | Partition Key (PK) | Cognito User Sub ( sub claim) |
timestamp | String (S) | Sort Key (SK) | ISO-8601 Timestamp ( YYYY-MM-DDTHH:mm:ss.sssZ ) |
conversationId | String (S) | Attribute / GSI PK | Unique Session UUID ( conv_XXXXXXXXXX ) |
sender | String (S) | Attribute | user | assistant |
message | String (S) | Attribute | Raw question or model answer text |
citations | List (L) | Attribute | Array of JSON objects detailing S3 source metadata |
isFallback | Boolean (BOOL) | Attribute | true if answer triggered fallback card |
Platform ID Format Standards
- User ID:
us-east-1:a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d(Cognitosub)
- Conversation ID:
conv_<timestamp_ms>_<random_hex>
- Message ID:
msg_<timestamp_ms>_<random_alphanumeric>
🚀 Production Database Migrations
For environment provisioning and DynamoDB table updates, AWS CLI / Infrastructure as Code scripts manage table states.
DynamoDB Table Definition (AWS CLI Command)
aws dynamodb create-table \ --table-name nimbus_chat_history \ --attribute-definitions \ AttributeName=userId,AttributeType=S \ AttributeName=timestamp,AttributeType=S \ --key-schema \ AttributeName=userId,KeyType=HASH \ AttributeName=timestamp,KeyType=RANGE \ --billing-mode PAY_PER_REQUEST \ --region us-east-1
🔄 GitHub Actions CI/CD Pipeline & Secrets
The repository includes an automated GitHub Actions workflow (
.github/workflows/deploy.yml ) for building, linting, and verifying frontend builds.name: NIMBUS CI/CD Deployment
on: push: branches: [ main ] pull_request: branches: [ main ]
jobs: build-and-test: runs-on: ubuntu-latest defaults: run: working-directory: ./frontend steps: - name: Checkout Source Code uses: actions/checkout@v4
- name: Setup Node.js Environment uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' cache-dependency-path: frontend/package-lock.json
- name: Install Dependencies run: npm ci
- name: Verify TypeScript & Build Artifacts run: npm run build env: VITE_AWS_REGION: ${{ secrets.VITE_AWS_REGION }} VITE_COGNITO_USER_POOL_ID: ${{ secrets.VITE_COGNITO_USER_POOL_ID }} VITE_COGNITO_CLIENT_ID: ${{ secrets.VITE_COGNITO_CLIENT_ID }} VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}Required Repository Secrets
Set these in GitHub Settings -> Secrets and variables -> Actions:
-
VITE_AWS_REGION
-
VITE_COGNITO_USER_POOL_ID
-
VITE_COGNITO_CLIENT_ID
-
VITE_COGNITO_AUTHORITY
-
VITE_COGNITO_DOMAIN
-
VITE_API_BASE_URL
🛡 Security & Production Hardening
- OAuth 2.0 PKCE Protection: Authentication tokens are requested via Authorization Code Flow with PKCE (Proof Key for Code Exchange) to prevent code interception attacks.
- CORS Policy Hardening: API Gateway restricts allowed origin headers exclusively to verified production domains.
- Repository Hygiene: Local
.envfiles,node_modules/, anddist/builds are explicitly excluded from Git tracking via.gitignore.
- Least Privilege IAM Policies: Lambda execution roles are strictly scope-bound to query specific Bedrock Knowledge Bases and read/write to
nimbus_chat_historyDynamoDB table.
💡 Troubleshooting & Diagnostic Matrix
Issue Description | Potential Cause | Resolution Steps |
|---|---|---|
401 Unauthorized on /chat | Expired or missing Cognito JWT Access/ID Token. | Sign out of portal and re-authenticate to refresh session tokens in localStorage . |
403 Forbidden on API Gateway | CORS misconfiguration or missing Bearer prefix in header. | Verify header format: Authorization: Bearer <token> . Check API Gateway CORS settings. |
Citations Missing in UI | Bedrock returned unparsed S3 URIs or raw array. | Handled automatically by normalizeSources() in src/services/api.ts . |
PWA Install Prompt Not Displaying | HTTPS required or browser lacks PWA criteria. | Ensure site is served over HTTPS and manifest.webmanifest is loaded. |
Build Failure during npm ci | Out-of-sync package-lock.json . | Run npm install locally, update package-lock.json , and push changes. |
⏪ Deployment Rollbacks & Log Auditing
Rolling Back AWS Amplify Deployment
- Open AWS Amplify Console.
- Navigate to App Settings -> Build history.
- Select previous successful build commit.
- Click Redeploy this version.
Log Auditing via CloudWatch
To inspect API Gateway and Lambda execution logs:
# View live tail logs for Chat Lambda Functionaws logs tail /aws/lambda/nimbus-chat-handler --follow --region us-east-1
💻 Local Setup Guide (NPM)
Prerequisites
- Node.js: v18.x or v20.x (LTS)
- npm: v9.x or v10.x
Step-by-Step Setup
# 1. Clone the repositorygit clone <repository-url>
# 2. Change directory into the frontend foldercd NIMBUS_HACKATHON/frontend
# 3. Install project dependencies using exact lockfilenpm ci
# 4. Create your local environment file (.env)cat <<EOT > .envVITE_AWS_REGION=your-regionVITE_COGNITO_USER_POOL_ID=your-user-pool-idVITE_COGNITO_CLIENT_ID=your-client-idVITE_COGNITO_AUTHORITY=<cognito-authority-endpoint>VITE_COGNITO_REDIRECT_URI=localhost:5173/auth/callbackVITE_COGNITO_LOGOUT_URI=localhost:5173/VITE_COGNITO_DOMAIN=<cognito-domain>VITE_API_BASE_URL=<api-gateway-base-url>EOT
# 5. Start the Vite development servernpm run devAfter starting the server, open your browser and navigate to:
localhost:5173 Available NPM Scripts
Script | Command | Description |
|---|---|---|
npm run dev | vite | Starts local Vite development server with Hot Module Replacement (HMR). |
npm run build | tsc -b && vite build | Compiles TypeScript and generates production distribution artifacts in dist/ . |
npm run preview | vite preview | Locally previews the production build output from dist/ . |
npm ci | npm ci | Clean installs exact node_modules dependencies matching package-lock.json . |
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article