# AbroadOS Project Documentation

## Project Overview

**AbroadOS** is the operating system for international student life.

As an international student in the United States, I have personally experienced how overwhelming student life can become when important decisions are scattered across university emails, immigration documents, tax forms, insurance portals, leases, deadlines, and unfamiliar rules. Studying abroad is not only about attending classes. It is also about understanding taxes, health insurance, CPT and OPT, internships, housing leases, scams, finances, academic planning, documents, and knowing which official office to contact before making a high-stakes decision.

AbroadOS was built to solve the kind of confusion I wish someone had solved for me.

The platform helps international students turn scattered information into personalized dashboards, risk alerts, checklists, document summaries, deadlines, and advisor-ready reports. The goal is to help students feel less alone, less confused, and more prepared when navigating the systems around studying abroad.

**Live Demo:** https://abroados.vercel.app  
**GitHub Repository:** https://github.com/shobhit1kapoor/AbroadOS

---

## Problem Statement

International students face a unique combination of academic, legal, financial, healthcare, and daily-life challenges. These challenges are often fragmented across different systems and offices, including:

- University emails
- International office websites
- Tax forms and filing systems
- Health insurance portals
- Immigration documents
- Job and internship offer letters
- Housing leases
- Academic planning tools
- Financial records
- Scam or fraud messages

For many students, the biggest issue is not a lack of information. The issue is that the information is scattered, hard to interpret, and connected to high-stakes decisions.

A single mistake can:

- delay employment authorization
- create tax filing problems
- increase healthcare costs
- cause housing or lease issues
- expose students to scams
- create academic or financial stress
- affect immigration status

International students need more than a chatbot. They need a structured system that helps them understand what is urgent, what documents are missing, what risks exist, and what questions to ask the right official office or professional.

---

## Solution

AbroadOS is a centralized life-admin platform for international students.

It helps students manage:

- taxes
- tax filing readiness
- health insurance
- healthcare navigation
- visa and immigration document tracking
- CPT, OPT, STEM OPT, on-campus work, internships, and work authorization
- job and internship applications
- offer letter review
- housing and lease management
- scam and fraud detection
- budgeting and financial survival
- academic planning
- deadline tracking
- document organization
- advisor-ready reports
- university email/document understanding
- daily-life checklists
- emergency preparation
- student support resources

AbroadOS converts student information into structured outputs:

- personalized risk dashboards
- module-specific guidance
- document summaries
- missing document alerts
- checklist tasks
- deadline timelines
- scam risk analysis
- work authorization review
- tax readiness review
- advisor-ready summaries

The key idea is:

> Most tools answer questions. AbroadOS turns confusion into workflows.

---

## Target Users

AbroadOS is designed for:

- international undergraduate students
- international graduate students
- F-1 and J-1 students
- students applying for internships or jobs
- students navigating CPT, OPT, or STEM OPT
- students handling taxes, insurance, housing, documents, and deadlines
- university international offices as future partners
- career centers, housing offices, and student support teams

The initial demo scenario focuses on an F-1 Computer Science student in the United States, but the architecture can expand to other countries, universities, visa types, and student situations.

---

## Demo Student Scenario

The default user scenario is **Aarav Mehta**:

- Country of citizenship: India
- Country of study: United States
- University: University of Texas at Dallas
- Degree: Bachelor's
- Major: Computer Science
- Academic year: Sophomore
- Visa type: F-1
- Years in U.S.: 2
- Expected graduation: May 2028
- Main goal: Summer Software Engineering Internship
- Main concerns: CPT, taxes, health insurance, internship offer, housing lease
- Income: On-campus job
- Documents available: offer letter, W-2, insurance card, lease, resume

Example risk scenario:

Aarav receives a remote software engineering internship offer from NovaTech Labs. AbroadOS identifies that off-campus work may require authorization before starting, flags that weekly hours are missing from the offer letter, creates next steps, and generates questions for the DSO.

---

## Core Modules

### 1. Dashboard

The dashboard is the student command center. It shows:

- welcome summary
- active risk areas
- missing documents
- this week's action plan
- upcoming deadlines
- quick actions
- recommended workflow

### 2. AI Advisor

The AI Advisor gives structured responses in a consistent format:

- Risk Level
- Simple Answer
- Why This Matters
- Next Steps
- Documents Needed
- Who To Contact
- Questions To Ask
- Important Note

It is designed to guide preparation, not replace official advice.

### 3. TaxPath

TaxPath helps students prepare for tax filing conversations and document collection. It supports:

- tax readiness quiz
- document collection guidance
- possible forms to review
- risk flags
- tax checklist

It does not file taxes or provide final tax advice.

### 4. CareGuide

CareGuide helps students understand health insurance and healthcare navigation. It supports:

- insurance overview
- deductible, copay, coinsurance, and network explanations
- care location guidance
- medical bill explanation
- insurance document analysis

It does not diagnose or provide medical treatment.

### 5. WorkSafe

WorkSafe helps students prepare for employment authorization conversations. It supports:

- on-campus work review
- CPT preparation
- OPT and STEM OPT planning
- remote internship risk review
- offer letter analysis
- DSO question generation

It does not provide final immigration or legal advice.

### 6. Document Vault

Document Vault organizes and analyzes international student documents, including:

- passport
- visa stamp
- I-20 / DS-2019
- I-94
- EAD
- SSN / ITIN
- W-2
- 1042-S
- 1099
- offer letters
- leases
- insurance cards
- resumes

Each document can include:

- important details
- dates found
- missing information
- risk level
- recommended actions
- related module
- questions to ask

### 7. ScamShield

ScamShield analyzes suspicious messages, emails, job offers, rental listings, tax messages, scholarship messages, and immigration threats. It detects:

- fake job offers
- fake checks
- gift card scams
- fake government messages
- rental deposit scams
- phishing links
- urgent threats
- suspicious requests for SSN, passport, bank, or payment information

### 8. Career Hub

Career Hub helps students manage jobs and internships:

- resume analysis
- job description analysis
- internship tracker
- networking assistant
- offer decision helper

### 9. Academic Planner

Academic Planner supports:

- course tracking
- GPA calculator
- degree progress
- syllabus analysis
- study plan generation
- professor email drafting

### 10. Finance Planner

Finance Planner supports:

- monthly budgeting
- financial survival score
- campus job tracking
- scholarship tracking
- emergency fund planning

### 11. Housing Assistant

Housing Assistant supports:

- lease analysis
- rent reminders
- move-in checklist
- move-out checklist
- roommate agreement generation

### 12. Deadline Center

Deadline Center tracks:

- tax deadlines
- CPT application planning
- OPT planning
- insurance waiver dates
- tuition payments
- course registration
- lease notice periods
- passport expiry
- visa expiry
- travel signatures
- scholarship deadlines
- exams and assignments

### 13. Advisor Summary

Advisor Summary generates professional reports for:

- international office / DSO
- tax support
- health insurance office
- academic advisor
- career center
- housing office
- general student support

The report includes:

- student summary
- current concern
- relevant documents
- risk areas
- key facts
- questions for advisor
- recommended next steps
- important responsible AI note

---

## User Workflow

```mermaid
flowchart TD
    A["Student opens AbroadOS"] --> B["Creates or signs into account"]
    B --> C["Completes student profile"]
    C --> D["Adds documents or pastes text"]
    D --> E["Document Analyzer extracts key details"]
    E --> F["Risk Classifier checks high-risk categories"]
    F --> G["Workflow Engine creates tasks and deadlines"]
    G --> H["Dashboard shows risk cards and next steps"]
    H --> I["Student opens focused module"]
    I --> J["AbroadOS generates questions and checklist"]
    J --> K["Advisor Summary creates official conversation report"]
    K --> L["Student contacts DSO, advisor, tax support, insurance office, or other official source"]
```

---

## Technical Flow Chart

```mermaid
flowchart LR
    UI["Next.js + React UI"] --> Components["Reusable Components"]
    Components --> Services["Service Layer"]
    Services --> Profile["Profile Service"]
    Services --> Docs["Document Service"]
    Services --> Workflow["Workflow Service"]
    Services --> Chat["Chat Service"]
    Services --> AI["AI Service"]
    AI --> Adapter["AI Adapter"]
    Adapter --> Gemini["Gemini API"]
    Adapter --> Fallback["Safe Fallback Responses"]
    Docs --> Analyzer["Document Analyzer"]
    Analyzer --> Risk["Risk Classifier"]
    Risk --> Workflow
    Workflow --> Dashboard["Dashboard + Modules"]
    Services --> Storage["Storage Adapter"]
    Storage --> Supabase["Supabase Auth + Database"]
    Storage --> Local["Local fallback storage"]
```

---

## System Architecture

```mermaid
flowchart TB
    subgraph Client["Client Application"]
        Landing["Landing Page"]
        AppShell["App Shell"]
        Dashboard["Dashboard"]
        Modules["Product Modules"]
        Forms["Forms + Upload Inputs"]
        Reports["Advisor Reports"]
    end

    subgraph Frontend["Frontend Layer"]
        Next["Next.js App Router"]
        React["React Components"]
        Tailwind["Tailwind CSS"]
        Motion["Framer Motion"]
    end

    subgraph Domain["Domain Logic Layer"]
        Types["TypeScript Types"]
        RiskEngine["Risk Classifier"]
        DocAnalyzer["Document Analyzer"]
        PromptTemplates["Prompt Templates"]
        MockData["Seeded Student Scenario"]
    end

    subgraph Services["Service Layer"]
        AuthService["Auth Service"]
        ProfileService["Profile Service"]
        DocumentService["Document Service"]
        WorkflowService["Workflow Service"]
        AdvisorService["Advisor Service"]
        AIService["AI Service"]
    end

    subgraph External["External Services"]
        SupabaseAuth["Supabase Auth"]
        SupabaseDB["Supabase Database"]
        GeminiAPI["Gemini API"]
        Vercel["Vercel Hosting"]
        GitHub["GitHub Repository"]
    end

    Client --> Frontend
    Frontend --> Domain
    Frontend --> Services
    Services --> Domain
    AuthService --> SupabaseAuth
    ProfileService --> SupabaseDB
    DocumentService --> SupabaseDB
    WorkflowService --> SupabaseDB
    AIService --> GeminiAPI
    Next --> Vercel
    GitHub --> Vercel
```

---

## Data Model

AbroadOS defines TypeScript types for the main product objects:

- StudentProfile
- RiskLevel
- DocumentItem
- RiskAssessment
- ChecklistTask
- Deadline
- ChatMessage
- AdvisorSummary
- JobApplication
- BudgetItem
- InsuranceSummary
- TaxReadinessResult
- WorkAuthorizationReview
- HousingLeaseSummary
- ScamAnalysis
- DemoScenario
- DemoStep
- DemoBrief

The Supabase-ready schema supports:

- profiles
- documents
- document analyses
- risks
- tasks
- deadlines
- advisor summaries
- chat messages

---

## AI Design

AbroadOS uses an AI abstraction layer instead of directly tying the UI to one provider.

The AI layer supports:

- Gemini API integration
- OpenAI-ready structure
- fallback responses when no API key is available
- structured response objects
- responsible AI warnings
- module-specific prompts

AI functions include:

- getAdvisorResponse
- getTaxReadiness
- getInsuranceSummary
- getWorkAuthorizationReview
- analyzeDocument
- analyzeScam
- generateAdvisorSummary
- analyzeJobDescription
- analyzeLease
- analyzeResume

The AI Advisor response format is intentionally structured:

1. Risk Level
2. Simple Answer
3. Why This Matters
4. Next Steps
5. Documents Needed
6. Who To Contact
7. Questions To Ask
8. Important Note

This prevents the experience from feeling like an unstructured chatbot and keeps outputs useful for real student decisions.

---

## Responsible AI and Safety

AbroadOS is designed around responsible AI. The platform never claims to provide final legal, immigration, tax, medical, insurance, housing, or financial advice.

### Immigration / Work Authorization

AbroadOS helps students prepare, organize, and understand possible next steps, but final decisions must be confirmed with a university international office, DSO, immigration attorney, or official government source.

### Taxes

AbroadOS helps with tax readiness and document organization, but it does not replace a tax professional, university tax support, or official tax software.

### Health

AbroadOS can explain insurance and care options, but it does not diagnose or provide medical treatment.

### Housing / Legal Topics

AbroadOS can summarize and flag lease concerns, but it does not replace legal advice.

### High-Risk Categories

AbroadOS always treats the following as high-risk or critical:

- starting off-campus work
- CPT / OPT / STEM OPT
- remote internships
- unpaid internships
- 1099 / freelance work
- tax filing status
- Social Security / Medicare tax withholding
- medical bills
- emergency healthcare
- lease termination
- eviction
- scams involving SSN, passport, bank account, gift cards, fake checks, rent deposits, or immigration threats

The goal is not to replace official decision-makers. The goal is to help students prepare better before talking to them.

---

## Technology Stack

### Frontend

- Next.js App Router
- React
- TypeScript
- Tailwind CSS
- Framer Motion
- Lucide React

### Backend / Platform

- Supabase-ready architecture
- Supabase Auth
- Supabase database schema
- Local fallback storage
- Service-layer design

### AI

- Gemini API
- AI adapter layer
- Structured prompt templates
- Responsible AI guardrails
- Mock/fallback responses

### Development and Deployment

- Node.js
- npm
- ESLint
- GitHub
- Vercel

---

## Repository Structure

```text
app/
  page.tsx
  dashboard/page.tsx
  ai-advisor/page.tsx
  tax/page.tsx
  insurance/page.tsx
  visa-work/page.tsx
  documents/page.tsx
  scam-shield/page.tsx
  career/page.tsx
  academics/page.tsx
  finance/page.tsx
  housing/page.tsx
  deadlines/page.tsx
  advisor-summary/page.tsx
  settings/page.tsx
  sign-in/page.tsx

components/
  AppShell.tsx
  Sidebar.tsx
  Topbar.tsx
  RiskBadge.tsx
  ModuleCard.tsx
  DashboardCard.tsx
  ChecklistItem.tsx
  DeadlineCard.tsx
  DocumentUploadBox.tsx
  DocumentSummaryCard.tsx
  ChatWindow.tsx
  ProfileForm.tsx
  ReportViewer.tsx
  StatCard.tsx

lib/
  types.ts
  mock-data.ts
  mock-ai.ts
  prompts.ts
  risk-classifier.ts
  document-analyzer.ts
  utils.ts
  services/
    ai-service.ts
    auth-service.ts
    profile-service.ts
    document-service.ts
    workflow-service.ts
    advisor-service.ts
    chat-service.ts
    storage-service.ts
    supabase-client.ts

supabase/
  schema.sql

styles/
  globals.css
```

---

## Scalability and Feasibility

AbroadOS was intentionally built as an MVP foundation, not just a visual prototype.

### Scalability

- The app uses a modular architecture with separate pages for taxes, insurance, work authorization, documents, scams, career, academics, finance, housing, deadlines, and advisor summaries.
- Each module can be expanded independently without rebuilding the entire platform.
- The service layer separates UI, AI logic, risk classification, document analysis, profile storage, workflow data, and authentication.
- Supabase-ready architecture allows future scaling for real user accounts, durable profiles, document records, analysis history, deadlines, tasks, and advisor reports.
- AI providers are abstracted behind an adapter layer, so Gemini, OpenAI, or future models can be swapped or combined.
- The app can support more universities, visa types, countries, and student scenarios over time.
- Future document upload, OCR, email parsing, and calendar integrations can plug into the existing workflow system.

### Feasibility

- AbroadOS is already implemented as a working deployed web app.
- It has a live Vercel deployment and a GitHub repository.
- The frontend is built with production-friendly technologies: Next.js, React, TypeScript, Tailwind CSS, and reusable components.
- The app includes authentication and database-ready infrastructure through Supabase.
- The AI layer supports Gemini API integration with safe fallback behavior.
- The MVP avoids overengineering while keeping the foundation ready for production expansion.
- The first real production milestone would be secure document storage, persistent user workflows, and deeper AI document extraction.

### Business and Adoption Feasibility

- International students are a clear target user group with recurring needs every semester.
- Universities, international offices, student support teams, and career centers could become future partners.
- The product can start as a direct-to-student tool and later expand into university-supported deployments.
- The platform solves repeated, high-stakes problems, which makes it useful beyond a one-time interaction.

> AbroadOS is feasible because the MVP is already functional, and it is scalable because the product is built around modular workflows, service abstractions, responsible AI, and durable student-life data.

---

## Impact and Innovation

AbroadOS matters because it addresses a real, emotional, and high-stakes problem.

International students are often far from home and navigating systems they did not grow up with. They may not know how U.S. tax filing works, whether an internship requires CPT, what a deductible means, whether a lease clause is expensive, or whether a job offer is a scam.

AbroadOS helps by:

- reducing confusion
- making next steps visible
- organizing documents
- identifying risk areas
- preparing advisor questions
- creating official conversation summaries
- helping students avoid costly mistakes

The innovation is that AbroadOS combines AI with structured workflows. Instead of only giving text answers, it creates an operating system for student life.

---

## Future Roadmap

Future improvements include:

- secure real document upload
- OCR and PDF parsing
- email parsing for university messages
- calendar integrations
- university-specific rule packs
- personalized CPT / OPT / tax / insurance timelines
- mobile-first app experience
- advisor collaboration portal
- student support resource directory
- advanced scam intelligence
- multi-country support beyond the United States
- partnerships with universities and international student offices

---

## Conclusion

AbroadOS is built from a real international student pain point.

The goal is to help students feel less alone, less confused, and more prepared when navigating the high-stakes systems around studying abroad.

It is not just a chatbot. It is a complete student life-admin platform that turns scattered information into structured guidance, risk alerts, checklists, timelines, and advisor-ready summaries.

**Live Demo:** https://abroados.vercel.app  
**GitHub Repository:** https://github.com/shobhit1kapoor/AbroadOS