Local Development

Day-to-day development workflow for the Dissertation Editor Platform.

Frontend Development

The frontend is a Next.js application located at platform/frontend/.

Running the Dev Server

cd platform/frontend
npm run dev

This starts the Next.js dev server at http://localhost:3000 with hot module replacement.

Environment Variables

Create a .env.local file in the frontend directory:

NEXT_PUBLIC_TOKEN_ENDPOINT=https://jwfqmc0638.execute-api.us-east-1.amazonaws.com/token

This tells the frontend where to fetch LiveKit tokens. In local development, this points to the deployed API Gateway endpoint since the token Lambda runs in AWS.

Additional environment variables may be needed depending on which features you are working on. See Environment Variables for a complete reference.

Building for Production Locally

cd platform/frontend
npm run build
npm start

This produces an optimized build and serves it on port 3000, which is useful for verifying production behavior before pushing.

Backend Development

The backend consists of AWS Lambda functions managed by Serverless Framework, located at platform/backend/.

Testing Lambda Functions Locally

Use serverless invoke local to test individual functions without deploying:

cd platform/backend

# Invoke a function with a test event
AWS_SDK_LOAD_CONFIG=1 npx serverless invoke local \
  --function submitIntake \
  --path test/events/submitIntake.json \
  --aws-profile dissertation-editor

The --path flag reads a JSON file as the event payload. Create test events in test/events/ for each function.

Example test event for getPresignedUrl (test/events/getPresignedUrl.json):

{
  "body": "{\"fileName\": \"test-dissertation.docx\"}"
}

Deploying Backend Changes

After making changes to Lambda functions, deploy to the dev stage:

cd platform/backend
AWS_SDK_LOAD_CONFIG=1 npx serverless deploy --aws-profile dissertation-editor

To deploy a single function (faster for iterative development):

AWS_SDK_LOAD_CONFIG=1 npx serverless deploy function \
  --function submitIntake \
  --aws-profile dissertation-editor

Single-function deploys update only the Lambda code and skip CloudFormation, making them significantly faster.

Viewing Logs

Tail CloudWatch logs for a specific function:

AWS_SDK_LOAD_CONFIG=1 npx serverless logs \
  --function submitIntake \
  --tail \
  --aws-profile dissertation-editor

Git Workflow

All development follows this branching model:

  1. Create a feature branch from staging:

    git checkout staging
git pull origin staging
git checkout -b feature/my-feature

  2. Commit early and often as you work.

  3. Push your branch and open a PR to staging:

    git push -u origin feature/my-feature

  4. After review and merge to staging, Amplify auto-deploys the frontend for testing.

  5. Once verified, open a PR from staging to main for production release.

See Deployment for full CI/CD details.

Common Tasks

Adding a New API Endpoint

  1. Create the Lambda handler in platform/backend/src/
  2. Add the function definition to serverless.yml
  3. Deploy: npx serverless deploy --aws-profile dissertation-editor
  4. Update the frontend API client if needed

Updating the Rate Schedule

Rate configuration lives in DynamoDB, not in code. See Rate Schedule Update.

Testing the Full Intake Flow

  1. Start the frontend (npm run dev)
  2. Navigate to http://localhost:3000/submit
  3. Upload a .docx file and complete the form
  4. Watch the submission process via CloudWatch logs