FlowEbb is a web application that provides tide information and predictions using NOAA data. It consists of a Next.js frontend, Go backend running on AWS Lambda, and infrastructure managed with Terraform.
- Node.js v18 or later
- Go 1.21 or later
- Docker Desktop
- AWS SAM CLI
- AWS CLI configured with appropriate credentials
- Terraform v1.5.0 or later
- Git
- IntelliJ IDEA (recommended IDE)
flowebb/
├── frontend/ # Next.js frontend application
├── backend-go/ # Go backend application
├── infrastructure/ # Terraform infrastructure code
├── scripts/ # Development and deployment scripts
└── docs/ # Documentation
- Clone the repository:
git clone https://github.com/bbernstein/flowebb.git
cd flowebb
- Install frontend dependencies:
cd frontend
npm install
cd ..
- Configure Docker network for SAM:
docker network create sam-network
The easiest way to start all components is using the development script:
./scripts/dev.sh
This script will:
- Start DynamoDB Local and Admin UI
- Initialize DynamoDB tables
- Start the SAM API
- Start the Next.js frontend
If you prefer to start components individually:
- Start DynamoDB Local:
docker-compose up -d
./scripts/init-local-dynamo.sh
- Start the backend:
cd backend-go
./scripts/gostart.sh
- Start the frontend:
cd frontend
npm run dev
The application will be available at:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8080
- DynamoDB Admin: http://localhost:8001
- Create a new feature branch from main:
git checkout -b feature/your-feature-name
- Make your changes and commit following conventional commit messages:
git add .
git commit -m "feat: add new feature"
- Push your branch and create a Pull Request on GitHub:
git push -u origin feature/your-feature-name
Before submitting a PR, run the verification script:
./scripts/verify-local.sh
This performs:
- Frontend linting (
npm run lint
) - Go linting and tests
- Terraform formatting and validation
cd frontend
npm test
cd backend-go
# Run tests with coverage
go test -coverprofile=test-results/coverage.out -covermode=atomic -coverpkg=./... ./...
# Generate coverage report
go tool cover -html=test-results/coverage.out -o test-results/coverage.html
Coverage requirements:
- Backend: Minimum 80% coverage
- Frontend: Minimum 70% coverage
- Use the debug script:
./scripts/debug-sam.sh TidesFunction
- In IntelliJ IDEA:
- Create a "Remote JVM Debug" configuration
- Set port to 5005
- Start debugging
- Use Chrome DevTools or the built-in debugger in IntelliJ IDEA
- React Developer Tools extension is recommended
Production deployments are automated via GitHub Actions when merging to main:
- Infrastructure changes are applied first using Terraform
- Backend Lambda functions are deployed
- Frontend is built and deployed to CloudFront/S3
If needed, components can be deployed manually:
./scripts/deploy-frontend.sh prod
./scripts/deploy-go-lambda.sh
cd infrastructure/terraform/environments/prod
terraform init
terraform plan
terraform apply
The infrastructure is configured using Terraform variables. To get started:
- Copy the example configuration:
cp infrastructure/terraform/environments/prod/terraform.tfvars.example infrastructure/terraform/environments/prod/terraform.tfvars
- Edit
terraform.tfvars
with your specific values:aws_region
: Your AWS region (e.g., "us-east-1")project_name
: Your project identifierdomain_name
: Your root domainfrontend_domain
: Domain for the frontend applicationapi_domain
: Domain for the API
Note: The terraform.tfvars
file contains sensitive configuration and is excluded from version control.
Frontend (.env.development, .env.production):
NEXT_PUBLIC_API_URL=http://localhost:8080 # Development
NEXT_PUBLIC_API_URL=https://api.flowebb.com # Production
Backend (environment variables in template.yaml):
Environment:
Variables:
LOG_LEVEL: debug
CACHE_ENABLE_LRU: "true"
CACHE_ENABLE_DYNAMO: "true"
- Lambda function logs: /aws/lambda/flowebb-*
- API Gateway logs: /aws/apigateway/flowebb-*
- stations-cache: Cached station data
- tide-predictions-cache: Cached tide predictions
- CloudWatch alarms are configured for Lambda errors
- API Gateway dashboard provides request metrics
This project is licensed under the MIT License - see the LICENSE file for details.