TimeBack Home
What is TimeBack Home?
TimeBack Home is the student home application: a full-stack web app on AWS that students reach after an LTI launch from TimeBack. It provides:
- Backend API — A serverless API built with Hono on AWS Lambda, with contract-first oRPC routes, OpenAPI documentation, Cognito authentication, and LTI 1.3 launch (
POST /authentication/v1/lti/1.3/launch) that completes through a magic-link Cognito custom challenge. - Frontend SPA — A React single-page application built with Vite, Redux Toolkit, and Tailwind CSS, served via CloudFront. Routes today:
/,/sign-in, and/sign-up. - Infrastructure as Code — AWS CDK stacks that provision API Gateway, Lambda, Cognito, CloudFront, S3, and supporting observability. PostgreSQL runs on a product-owned Aurora cluster looked up at deploy time; the stack does not create RDS.
Quick Links
- Getting Started — Set up your local development environment and run the application.
- Architecture — Backend layered pattern, frontend modules, and dependency injection.
- CI/CD & Environments — Deployment workflows, environment types, and the release pipeline.
- Environment Reset — Wipe and reseed an ephemeral environment to a clean baseline in one command.
- API Reference — Interactive API documentation auto-generated from the deployed OpenAPI specification.
High-Level Architecture
The repository is organized as a pnpm monorepo with seven workspace packages:
| Package | Path | Purpose |
|---|---|---|
backend |
apps/backend/ |
Hono API server, Lambda handlers, DI containers, business logic |
frontend |
apps/frontend/ |
React SPA with Vite, Redux Toolkit, and Tailwind CSS |
infra |
apps/infra/ |
AWS CDK constructs and stacks for cloud resources |
shared |
packages/shared/ |
Shared TypeScript types, constants, and oRPC API contracts |
api-tests |
packages/api-tests/ |
Auto-generated and hand-written integration tests for the API |
sync |
packages/sync/ |
Upstream sync tool for pulling starter improvements |
eslint-rules |
packages/eslint-rules/ |
Shared ESLint rules for the monorepo |
The shared package acts as the single source of truth for API contracts. Backend oRPC routers implement contracts from packages/shared/api/, the frontend builds typed oRPC clients from those contracts, and API tests use the same contracts for typed calls.
Environments
TimeBack Home supports three environment types:
| Type | Name Pattern | Purpose | Lifecycle |
|---|---|---|---|
| Production | production |
Live user-facing environment | Manual deploy via workflow_dispatch |
| Integration | integration |
Staging and continuous integration | Auto-deploys on merge to master |
| Ephemeral | pr0001–pr9999 |
Per-PR preview environments | Auto-created on PR, destroyed on close |
Key differences between environments:
- PostgreSQL: Each environment uses database
tb_home_app_<env>on the shared Aurora cluster; data lifecycle is managed outside ephemeral stack teardown. - Self-signup: Enabled on ephemeral environments for easier testing; disabled on integration and production.
- SSO sign-in: Not shipped (
ssoSignInEnabledis false in published environment config). - Source maps: Included in integration and ephemeral builds for easier debugging; excluded from production.
For a full comparison, see the CI/CD & Environments guide.
