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, sevDesk, DocuSign, Azure Entra,
                        Dataverse, Resend, Bird (SMS),
                        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

File counts as of 2026-06 (excluding co-located tests):

renewa-one/
├── backend/          # Bun + Hono API server
│   ├── src/
│   │   ├── routes/       # 199 route files (OpenAPI)
│   │   ├── services/     # 148 service files
│   │   ├── lib/          # 163 utility modules (incl. jobs/, billing/, file-operations/)
│   │   ├── middleware/   # 11 middleware modules
│   │   ├── interfaces/   # 71 interface definitions
│   │   └── db/           # Schema, mocks, shared schemas
│   └── atlas/            # Atlas migration SQL files (48)
├── frontend/         # React 19 + Vite SPA
│   ├── src/
│   │   ├── pages/        # 167 page components
│   │   ├── components/   # ~620 components
│   │   ├── hooks/        # 39 custom hooks
│   │   └── lib/          # API clients, queries, utils
│   ├── e2e/              # Playwright end-to-end tests
│   └── public/
├── shared/           # Cross-cutting types, constants, money arithmetic
├── scripts/          # Developer tooling
├── docker/           # Docker configuration
├── .github/          # 19 GitHub Actions workflows (repo root)
└── infrastructure/   # IaC / infra configuration

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, 187 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
• Persistence Topology — Who may import the DB layer
• Dependency Injection — Container and context pattern
• Security Scanning — Trivy, Semgrep, Gitleaks