• Why this project
• Features
• Stack
• Quick start
• Project layout
• Database (reference)
• Development
• API overview
• Testing
• Deployment
• Contributing
• License & acknowledgments

Missouri Crossroads (MOX) is a free, open-access platform for discovering and managing Missouri’s cultural and historical places. It combines a responsive map UI with AWS-backed APIs for data, auth, and admin workflows—built for researchers, educators, and the public.

• App: Next.js (App Router), React, TypeScript, Tailwind CSS
• Map: Google Maps Platform
• Cloud: AWS (Cognito, DynamoDB, S3; deployable via Amplify—see CI docs)
• Quality: ESLint, Prettier, Jest, Playwright

• Node.js 18+
• pnpm (recommended) or npm
• AWS account (S3, DynamoDB, Cognito) and Google Maps API keys for full functionality

git clone https://github.com/yashb196/Missouri-Crossroads.git
cd Missouri-Crossroads
pnpm install

cp .env.example .env.local

# AWS (public / client-safe)
NEXT_PUBLIC_AWS_REGION=us-east-2
NEXT_PUBLIC_COGNITO_USER_POOL_ID=your_user_pool_id
NEXT_PUBLIC_COGNITO_CLIENT_ID=your_client_id
NEXT_PUBLIC_DYNAMODB_USERS_TABLE=missouri-crossroads-users
NEXT_PUBLIC_DYNAMODB_NOTES_TABLE=missouri-crossroads-notes
NEXT_PUBLIC_DYNAMODB_ADMIN_LOGS_TABLE=missouri-crossroads-admin-logs

# AWS (server-only — never use NEXT_PUBLIC_ for secrets)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
S3_BUCKET_NAME=mr-crossroads-bucket
COGNITO_CLIENT_SECRET=your_client_secret

# Google Maps (domain-restricted keys recommended)
NEXT_PUBLIC_MAP_KEY=your_google_maps_api_key
NEXT_PUBLIC_PLACES_KEY=your_google_places_api_key

pnpm dev

Open http://localhost:3000.

├── app/                 # Routes, layouts, UI
│   ├── api/             # REST handlers (admin, auth, database, map)
│   ├── lib/             # Config, models, utilities
│   └── map/             # Map experience
├── components/ui/       # Shared UI (e.g. shadcn-style primitives)
├── public/              # Static assets
├── tests/               # Playwright E2E specs
└── types/               # Shared TypeScript types

{
  "id": "user-1234567890-abc123def",
  "email": "user@example.com",
  "name": "John Doe",
  "preferredUsername": "johndoe",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "lastLogin": "2024-01-01T12:00:00.000Z",
  "isActive": true,
  "role": "user"
}

{
  "id": "note-1234567890-abc123def",
  "title": "My Note",
  "bodyText": "This is my note content",
  "creator": "user-1234567890-abc123def",
  "creatorEmail": "user@example.com",
  "type": "note",
  "media": ["https://s3.../image1.jpg"],
  "audio": ["https://s3.../audio1.mp3"],
  "latitude": 39.0997,
  "longitude": -94.5786,
  "published": true,
  "tags": ["important", "work"],
  "time": "2024-01-01T00:00:00.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

pnpm dev              # Dev server (Turbopack)
pnpm build            # Production build
pnpm start            # Run production build locally

pnpm test             # Unit + E2E
pnpm test:watch       # Jest watch
pnpm test:coverage    # Coverage report

pnpm lint             # ESLint
pnpm lint:fix         # ESLint --fix
pnpm format           # Prettier

• Admin UI, CSV upload, or API—see endpoints below.

pnpm test
pnpm test MissouriMap.test.tsx   # single file
pnpm test:coverage
pnpm test:e2e                     # Playwright (see tests/README.md)

1. Configure production env vars on your host (Amplify, Vercel, etc.).
2. Ensure Google Maps keys allow your production domain.
3. Build: pnpm build — for AWS Amplify and GitHub Actions integration, see .github/GITHUB_ACTIONS.md.

1. Fork the repo and create a branch: git checkout -b feature/your-feature
2. Make changes and run pnpm test
3. Open a PR against main

Issues welcome: github.com/yashb196/Missouri-Crossroads/issues

Licensed under the MIT License — see LICENSE.

Thanks to contributors and partners in Missouri’s heritage community, Google Maps Platform, AWS, and the Next.js team.