Architecture Overview

Renewa One is a monorepo application deployed as a single Docker container running nginx, a Bun+Hono backend, and serving React static assets.

System Diagram

                        ┌─────────────────────────────┐
                        │         Fly.io              │
                        │                             │
  Browser ──────────────┤► nginx (:80)                │
                        │   ├── /api/*  ──► backend   │
                        │   │              (:3000)    │
                        │   └── /*      ──► static    │
                        │                  (React)    │
                        │                             │
                        │   backend ──────────────────┤──► PostgreSQL (Fly.io managed)
                        │              │              │        via PgBouncer
                        │              └──────────────┤──► Upstash Redis
                        └─────────────────────────────┘
                                       │
                              External Services:
                        HubSpot, DocuSign, Azure Entra,
                        Dataverse, Resend, MessageBird,
                        Sentry, Tigris (S3)

Request Flow

1. All traffic enters through nginx on port 80
2. Requests to /api/* are proxied to the Hono backend on port 3000
3. All other requests serve the React SPA static bundle
4. Backend connects to PostgreSQL (via PgBouncer) and Redis (via Upstash)

See Backend Middleware for the middleware stack processing order: security → CORS → sanitization → rate limiting → auth → routes.

Monorepo Structure

renewa-one/
├── backend/          # Bun + Hono API server
│   ├── src/
│   │   ├── routes/       # 164 route files (OpenAPI)
│   │   ├── services/     # 98 service files
│   │   ├── lib/          # 126 utility modules
│   │   ├── middleware/   # 10 middleware modules
│   │   ├── interfaces/   # 48 interface definitions
│   │   └── db/           # Schema, seeds, migrations
│   └── atlas/            # Atlas migration SQL files
├── frontend/         # React 19 + Vite SPA
│   ├── src/
│   │   ├── pages/        # 96 page components
│   │   ├── components/   # 623+ components
│   │   ├── hooks/        # 43 custom hooks
│   │   └── lib/          # API clients, queries, utils
│   └── public/
├── shared/           # Cross-cutting types and constants
├── scripts/          # Developer tooling
├── docker/           # Docker configuration
├── .github/          # 20 GitHub Actions workflows
└── infrastructure/   # Terraform / IaC

Key Architectural Decisions

Decision	Choice	Rationale
Runtime	Bun	Fast startup, native TypeScript, built-in test runner
Framework	Hono	Lightweight, OpenAPI support, middleware-based
ORM	Drizzle	Type-safe, thin abstraction, PostgreSQL-native
Migrations	Atlas	Declarative schema diffing, integrity checksums
Frontend	React 19 + Vite	Industry standard, fast HMR, large ecosystem
State	React Query + Zustand	Server state separated from client state
Styling	TailwindCSS 4 + Shadcn/ui	Utility-first, accessible component primitives
Deployment	Fly.io	Edge deployment, managed Postgres, simple scaling

Configuration

File	Purpose
fly.development.toml	Fly.io dev environment config
fly.staging.toml	Fly.io staging config
fly.production.toml	Fly.io production config
nginx.conf / nginx.dev.conf	nginx reverse proxy config
docker-compose.yml	Local development stack
Dockerfile	Multi-stage production build
tsconfig.base.json	Shared TypeScript config

Related Pages

• Backend Architecture — Hono framework, DI, service layer
• Frontend Architecture — React, component library, routing
• Database Architecture — PostgreSQL, Drizzle, 140 tables
• Shared Layer — Cross-cutting types and validation
• Deployment Pipeline — CI/CD and image promotion
• Docker Setup — Local development containers
• Middleware Stack — Request processing pipeline
• Service Layer Pattern — Business logic organization
• Dependency Injection — Container and context pattern
• Security Scanning — Trivy, Semgrep, Gitleaks