⚠️ Note: This is a public sample repository that demonstrates the technical architecture and initial implementation of the Offering Bowl platform. The live production version is maintained in a private repository with additional features and security measures.
This repository serves as a technical demonstration and reference implementation. If you're interested in contributing to the actual Offering Bowl platform, please:
- Contact nickpettican directly
- Include your GitHub username and areas of expertise
- Specify which aspects of the platform you'd like to contribute to
The core platform includes enhanced features, security measures, and optimizations not present in this sample implementation.
Offering Bowl is a platform designed to connect Buddhist monastics with patrons who can sponsor them through one-time or recurring donations. Inspired by platforms like Patreon, Offering Bowl focuses exclusively on the unique needs of monastics, providing a space for updates, messages, and sponsorship opportunities.
This sample repository demonstrates:
- Basic monastic profile structure
- Sponsorship system architecture
- Authentication flow
- Database schema design
- Infrastructure setup
- Docker containerization
- CI/CD pipeline configuration
- Backend: Node.js with Express.js (TypeScript)
- Frontend: Vue.js (TypeScript)
- Database: AWS DynamoDb
- Authentication: Firebase
- File Storage: AWS S3 and Firebase Storage
- Containerization: Docker
- Deployment: AWS EC2 and CloudFront
- CI/CD: GitHub Actions
Ensure the following are installed on our system:
- Node.js (tls/jot or v22.11.0 or higher)
- npm (v10.9.0 or higher)
- Docker (version 27.3.1 or higher)
- Git
-
Clone the Repository:
git clone https://github.com/nickpettican/offering-bowl.git cd offering-bowl -
Install Dependencies:
Server:
cd server npm installClient:
cd ../client npm install -
Set Up Environment Variables:
Create a
.envfile in the root directory and populate it based on the.env.example.Bear in mind that for
docker composewe use.env. -
Run the Development Environment:
Use Docker Compose to start the client, back-end and database services together:
npm run dev
or
docker compose --env-file .env up --build
Otherwise see the scripts section for more information.
-
Access the Application:
- Backend: http://localhost:SERVER_PORT
- Frontend: http://localhost:CLIENT_PORT
This project uses husky for Git hooks to ensure code quality before commits. After cloning the repository and installing dependencies, you'll need to initialize husky:
# Install dependencies first
npm ci
# Initialize husky
npx husky installNote: If you don't initialize husky, Git hooks won't run and you may commit code that doesn't meet the project's quality standards.
For development we use the Docker image amazon/dynamodb-local:2.5.3.
If we run docker compose it will automatically be set up (see Docker section bellow).
In dev, however, to create the tables in the database for now we have to use services/db-initialiser. See the README there for more information.
For the AWS credentials we can add any dummy values. For region I recommend eu-south-2 and a simple ID and secret like LOCAL.
Table definitions match the production tables defined in the CDK infrastructure. Any changes to table structures should be made in both:
infra/lib/constructs/database.ts(for production)services/db-initialiser/dynamodb.ts(for development)
Run these commands from the server/ directory:
-
Start Development Server:
Dev:
npm run start
-
Quality Control:
This will execute tests, eslint, ts type checking and prettier.
npm run qc
We can also run each QC step separately (see scripts in
server/package.json). -
Build:
Dev:
npm run build
Run these commands from the client/ directory:
-
Compile and Hot-Reload for Development:
Dev:
npm run dev
-
Type-Check, Compile and Minify for Production:
npm run build
-
Run Unit Tests with Vitest:
npm run test:unit
-
Run End-to-End Tests:
See
client/README.mdfor more information.
For detailed information about docker compose read the docs.
If using docker compose bear in mind that each service communicates with each other not via localhost but by the name of the respective container. For instance ob-server will find dynamodb under http://dynamodb:PORT.
Use .env for this (see the compose.yml file).
An important consideration is that of the environment variables.
| Path | Name | Purpose | Considerations |
|---|---|---|---|
| . | .env | for building all apps on docker compose | used by docker compose by default unless --env-file is specified |
| . | .env.local | for running services locally | can be used by docker compose with --env-file |
| server/ | .env | for running the app in docker compose | used by running ob-server container in docker compose |
| server/ | .env.local | for running the app locally | used by default by node (see server/src/_config/env.vars.ts) |
| server/ | .env.test | for running tests, absolutely necessary | |
| client/ | .env | for running the app in docker compose (OPTIONAL) | used by running ob-client container in docker compose |
| client/ | .env.local | for running the app locally (OPTIONAL) | used by default by vite |
If environment variables are passed by --env-file to docker compose, and these variables are mapped into a container using environment:, they will override any variables in service/.env even if they are passed to the container via env_file:.
Without adding the --env-file option the .env file in the parent directory will be used for the environment building the containers and the variables here can be passed to the container through environment: in compose.yml.
Here we specified --env-file .env to make it exclusive for docker compose. However, this is optional.
-
Build the Docker images:
docker compose --env-file .env build --no-cache
-
Start the containers:
docker compose --env-file .env up --build
-
Stop the containers:
docker compose down
On each push and pull-request to the main branch:
-
Code is tested and linted.
-
Docker images are built and pushed to the container registry.
The workflow is set up to only build the respective application if there are changes, otherwise these steps are skipped.
This sample repository:
- ✅ Demonstrates core architecture
- ✅ Shows basic implementation
- ✅ Includes development setup
- ✅ Provides infrastructure code
- ❌ Does not include production features
- ❌ Does not include sensitive configurations
- ❌ Does not contain live data models
We welcome contributions to this non-profit project!
Please commit any pull requests against the main branch. Contribution Guidelines will be set up soon.
This project is licensed under the Apache 2.0 License.
For questions or support, please contact:
Reminder: For access to the production repository and to contribute to the actual Offering Bowl platform, please reach out directly rather than forking this sample repository.