How To Guides: Starter Code Setup Instructions
The goal of the starter code is to provide a foundation for the Three Moves Ahead health application, including authentication, a few API Endpoints and starter web / mobile screens, and development tooling. You all will design and build the rest!
How the Code is Organized
1. Development Architecture
For development, the app is organized as follows:
- The database server, backend server (FastAPI), and frontend server (React) each run in their own container managed by
docker-compose.yaml. - Expo (for mobile, React Native development) is not containerized, and must run it on your local system. That said, it can still interact with the containerized FastAPI server (via localhost:8000).
┌─────────────────────────────────────────────────────────────┐
│ Your Laptop (Development) │
│ │
│ ┌──────────────┐ ┌────────────────┐ │
│ │ │ │ Frontend │ │
│ │ Browser │◀───────▶│ Container │ │
│ │ │ │ localhost:8000 │ │
│ │ │ │ (React) │ │
│ └──────────────┘ └──────┬─────────┘ │
│ │ │
│ ┌───────────────────┐ │ HTTP Requests │
│ │ Expo │ │ (localhost:8000) │
│ │ (npx expo start)│ │ │
│ │ iOS/Android │ │ │
│ │ Simulator │ │ │
│ └───────────────────┘ ▼ │
│ ▲ ┌────────────────┐ │
│ │ │ Backend │ │
│ └──────────────▶ | localhost:8000 │ │
│ HTTP Requests │ (FastAPI) │ │
│ (localhost:8000) └──────┬─────────┘ │
│ │ │
│ │ SQL Queries │
│ │ (Docker network) │
│ ▼ │
│ ┌──────────────┐ │
│ │ Database │ │
│ │ Container │ │
│ │ (PostgreSQL) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘2. Production
Single container serves both frontend (static) and backend (FastAPI). Mobile app built with EAS, distributed as APK/IPA.
┌─────────────────────────────────────────────────────────────┐
│ Browser Users │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Desktop │ │ Mobile │ │
│ │ Browser │ │ Browser │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│
│ HTTPS
│ (https://dev.tma.unca.info)
│
▼
┌────────────────────────────────────────────────────────────┐
│ Production (Railway) │
│ │
│ ┌────────────────────────────┐ │
│ │ Combined Container │ │
│ │ (Single Docker Image) │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Frontend (Static) │ │ │
│ │ │ Served from /static │ │ │
│ │ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Backend (FastAPI) │ │ │
│ │ │ Port: 8080 │ │ │
│ │ └──────┬───────────────┘ │ │
│ └─────────┼──────────────────┘ │
│ │ │
│ │ SQL Queries │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Managed PostgreSQL │ │
│ │ (Railway/Cloud DB) │ │
│ └──────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────┘
▲
│
│ HTTPS API Calls
│ (https://dev.tma.unca.info)
│
┌─────────────────────────────────────────────────────────────┐
│ Mobile Users │
│ │
│ ┌──────────────┐ ┌────────────────┐ │
│ │ iOS Device │ │ Android Device │ │
│ │ (IPA) │ │ (APK) │ │
│ └──────────────┘ └────────────────┘ │
│ │
│ Built with EAS (Expo Application Services) │
│ Distributed via App Store / Google Play / Direct Install │
└─────────────────────────────────────────────────────────────┘What’s Included
1. Backend (FastAPI + PostgreSQL)
Core Infrastructure:
- FastAPI server with async SQLAlchemy ORM
- PostgreSQL database with Docker setup
- JWT-based authentication system
- Role-based access control (admin, manager, user roles)
- Database migrations and seed data scripts
- CORS middleware configured
API Endpoints: https://dev.tma.unca.info/docs
Database Models:
User- User accounts with profile fieldsRole- System roles (user, manager, admin)Group- User groupsUserGroup- Many-to-many relationship between users and groupsCourse- Courses/projectsCourseGroup- Many-to-many relationship between courses and groups
Seed Data:
- Pre-populated CSV files for users, groups, courses
- Automatic role seeding on startup
- Sample data generation with Faker
2. Frontend (React + TypeScript + Mantine)
Core Infrastructure:
- React 19 with TypeScript
- Vite build tool
- Mantine UI component library
- React Router for navigation
- Context API for authentication state
Features:
- Authentication
- Admin Interface
- User Interface
UI Components:
- Layout components (AdminPageLayout, UserPageLayout)
- Data views (table and card views)
- Form components
- Navigation components
Web Demo: https://dev.tma.unca.info/
3. Mobile App (React Native + Expo)
Core Infrastructure:
- Expo SDK 54
- React Native with TypeScript
- Expo Router for file-based routing
- React Native Paper (Material Design 3)
- React Query for data fetching
- Fetch for API calls
- Expo Secure Store for token storage
Features:
- Authentication (login)
- Home screen
- Groups list and detail screens
- Basic navigation with bottom tabs
- Error boundary
- Protected routes
Note: Mobile app is simplified and primarily serves as a foundation for future development.
4. Development Tools
Docker & Docker Compose:
- PostgreSQL database container
- Backend API container with hot reload
- Frontend container with hot reload
- Volume mounts for development
- Health checks and dependency management
CI/CD:
- GitHub Actions workflow for linting and formatting
- Automated checks on push and pull requests
- Backend: Black, isort, Ruff
- Frontend: ESLint, Prettier
Code Quality:
- Pre-commit hooks (via CI)
- Consistent formatting rules
- TypeScript strict mode
- ESLint configuration
What’s NOT Included
The following features are intentionally excluded from the starter code and will be implemented during the course:
- Modules - Course module management
- Posts - Content posts within modules
- Quizzes - Quiz creation and taking
- File Upload - File upload and storage
- User Progress - Progress tracking for courses/modules
- Invites - User invitation system
- Email Verification - Email verification workflow
- Admin Impersonation - Admin user impersonation feature
- Complex UI Features - Advanced UI components and interactions
Setup Instructions
1. Prerequisites
- Docker & Docker Compose - For running backend and frontend
- Node.js 18.x or 20.x - For mobile app development (avoid 19.x or 21+)
- Git - Version control
- SSH key - For GitHub authentication
2. Initial Setup
-
ONE member of your team will fork the base repository, located here: https://github.com/csci373-apps/tma-starter-app. This person will then add the rest of their teammates as collaborators.
-
Clone the repository: Once everyone on your team has access to your version of the repository, each person will clone it:
git clone git@github.com:<teammates_github_handle>/tma-starter-app.git cd tma -
Create a new branch:
git checkout -b <your-username>-setup -
Create environment file:
cp .env.example .envEdit
.envif needed (defaults usually work for local development).
3. Backend + Web-UI Setup
-
Build your Docker images, volumes, and containers: First, make sure that Docker Desktop is running on your machine. Also, if you’ve previously built a container that also uses ports 5433, 5173, or 8000, please stop those containers before proceeding.
When you’re ready, issue the following command to build your containers:
docker compose up -dThis starts:
- PostgreSQL database on port 5433
- Backend API on port 8000
- Frontend on port 5173
-
Seed the database: After creating your containers, run the test database script to populate your database with fake information (just for testing). You can modify your fake data by navigating to
backend/scripts/sample_dataand editing the relevant CSV files with the data you want.docker exec -it tma_backend poetry run python scripts/populate.py --resetThe
--resetflag drops all tables and recreates them with fresh data. -
Access the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
Note, to login, use the test acconts:
- Admin account: admin/password
- User account: user/password
4. Mobile App Setup
The Mobile App Setup does not use Docker, so you will have to configure Expo and React Native manually.
Prerequisites:
- For iOS Simulator: Xcode (macOS only) - includes iOS Simulator
- For Android Emulator: Android Studio with Android SDK and an AVD (Android Virtual Device). See these instructions.
- For Physical Devices: Expo Go app installed on your phone
- iOS: Install from App Store
- Android: Install from Google Play
Setup Steps:
-
Navigate to mobile directory:
cd mobile -
Install dependencies:
npm install -
Create
.envfile:cp .env.example .envEdit
.envif needed. The app automatically uses the correct URL based on platform:Platform EXPO_PUBLIC_API_URLSettingDefault URL Used iOS Simulator Leave unset http://localhost:8000Android Emulator Leave unset http://10.0.2.2:8000Physical Mobile Device Set to your computer’s IP (e.g., http://192.168.1.228:8000)Uses the value you set -
Start Expo:
npx expo start -
Run on device:
- iOS Simulator: Press
i(only for Mac users…requires Xcode) - Android Emulator: Press
a(requires Android Studio with AVD) - Physical Mobile Device:
- Install Expo Go app on your phone (see Prerequisites above)
- Scan the QR code shown in the terminal with your device’s camera
- iOS Simulator: Press
5. Useful Commands
For a comprehensive list of development commands, see the Development Cheatsheet.
Project Structure
health-app/
├── backend/ # FastAPI backend
│ ├── models/ # SQLAlchemy models
│ ├── routes/ # API route handlers
│ ├── schemas/ # Pydantic schemas
│ ├── database/ # Database connection & migrations
│ ├── scripts/ # Seed data scripts
│ └── server.py # FastAPI app entry point
├── ui/ # React frontend
│ └── src/
│ ├── components/ # Reusable UI components
│ ├── pages/ # Page components
│ ├── contexts/ # React contexts
│ ├── hooks/ # Custom React hooks
│ └── utils/ # Utility functions
├── mobile/ # React Native mobile app
│ ├── app/ # Expo Router app directory
│ ├── components/ # React Native components
│ ├── services/ # API service functions
│ └── contexts/ # React contexts
├── database/ # Database Docker setup
├── docker-compose.yaml # Docker Compose configuration
└── .github/ # GitHub Actions workflowsNext Steps
- Explore the codebase - Familiarize yourself with the structure
- Review the API - Check out
/docsendpoint for API documentation - Read the code - Understand how authentication, routing, and data flow work
- Check the seed data - Look at
backend/scripts/sample_data/to understand the data model - Start implementing - Begin with the first homework assignment!