Skip to content

Commit eceb2f3

Browse files
jacktoncellijacktoncelli
authored
readme (#225)
1 parent ddf5354 commit eceb2f3

File tree

2 files changed

+151
-37
lines changed

2 files changed

+151
-37
lines changed

‎README.md‎

Lines changed: 149 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -5,46 +5,158 @@ Prisere is an all-in-one platform to empower Small-Medium Sized Businesses (SMBs
55
## Table of Contents
66

77
1. [File Structure](#file-structure)
8-
2. [Deployments](#deployments)
8+
2. [Running the App](#running-the-app)
9+
3. [Database Management](#database-management)
10+
4. [Type Generation](#type-generation)
911

1012
### File-Structure
1113

1214
The template repository is laid out as follows below.
1315

1416
```bash
15-
├── .github
16-
│   ├── pull_request_template.md
17-
│   └── workflows
18-
│   └── backend-deploy.yml
19-
│  └── backend-lint.yml
20-
│  └── backend-test.yml
21-
├── backend # Backend source code
22-
│ └── src # main folder
23-
│ └── database # includes utilities for working with our database
24-
│ └── factories # factories for easily creating dummy data
25-
│ └── seeds # seeders for populating database with dummy data
26-
│ └── entities # TypeORM entities used for migrations
27-
│ └── migrations # Migrations created with typeORM
28-
│ └── modules # API endpoint files
29-
│ └── tests
30-
│ └── types
31-
│ └── utilities
32-
│   └── eslint.config.ts # configuration for eslint
33-
│   └── routes.ts # sets up routes for entire app
34-
│   └── server.ts # sets up server
35-
│   └── typeorm-config.ts # configuration for typeorm
36-
│   └── supabase # includes config for local supabase
37-
│   └── MIGRATION_TUTORIAL.md # guide to creating/running migrations
38-
│   └── .gitignore
39-
│   └── Dockerfile
40-
│   └── package.json
41-
│   └── README.md
42-
│   └── tsconfig.json
43-
├── CONTRIBUTING.md # Contribution documentation for engineers
44-
├── docker-compose.yaml
45-
├── frontend # Frontend source code
46-
├── LICENSE
47-
├── README.md
48-
```
49-
50-
### Deployments
17+
.
18+
├── README.md
19+
├── backend
20+
│ ├── Dockerfile # Container configuration for backend
21+
│ ├── README.md
22+
│ ├── bun.lock
23+
│ ├── package.json # Backend dependencies and scripts
24+
│ ├── requirements.txt # Python dependencies
25+
│ ├── src
26+
│ │ ├── database # Database utilities, factories, and seeds
27+
│ │ ├── dayjs.config.ts # Date/time library configuration
28+
│ │ ├── entities # TypeORM entity definitions
29+
│ │ ├── eslint.config.ts
30+
│ │ ├── external # Third-party integrations (Quickbooks)
31+
│ │ ├── lambda # AWS Lambda function handlers for email sending
32+
│ │ ├── migrations # Database migration files
33+
│ │ ├── modules # API endpoint modules
34+
│ │ ├── routes.ts # Route definitions and setup
35+
│ │ ├── server.ts # Express server entry point
36+
│ │ ├── tests # Backend test suites
37+
│ │ ├── typeorm-config.ts
38+
│ │ ├── types # TypeScript type definitions
39+
│ │ └── utilities # Helper functions and utilities
40+
│ ├── supabase
41+
│ │ ├── MIGRATION_TUTORIAL.md # Guide for database migrations
42+
│ │ ├── config.toml # Supabase configuration
43+
│ │ └── signing_key.json # JWT signing key for local auth
44+
│ ├── terraform
45+
│ │ ├── INSTRUCTIONS.md
46+
│ │ ├── backend.tf # Backend infrastructure definitions
47+
│ │ ├── iam.tf # IAM roles and policies
48+
│ │ ├── lambda.tf # Lambda function resources
49+
│ │ ├── main.tf # Main Terraform configuration
50+
│ │ ├── outputs.tf # Output values from Terraform
51+
│ │ ├── s3.tf # S3 bucket configurations
52+
│ │ ├── terraform.tfvars # Default Terraform variables
53+
│ │ ├── terraform.tfvars.dev # Development environment variables
54+
│ │ ├── terraform.tfvars.prod # Production environment variables
55+
│ │ └── variables.tf # Variable declarations
56+
│ └── tsconfig.json
57+
├── bun.lock
58+
├── docker-compose.yaml
59+
├── frontend
60+
│ ├── Dockerfile
61+
│ ├── README.md
62+
│ ├── actions
63+
│ │ └── auth.ts # Authentication server actions
64+
│ ├── api # API client layer
65+
│ ├── app # Next.js app directory (routes)
66+
│ ├── bun.lock
67+
│ ├── components # Reusable React components
68+
│ ├── components.json
69+
│ ├── eslint.config.mjs # ESLint configuration
70+
│ ├── icons # Custom icon components
71+
│ ├── lib
72+
│ │ └── utils.ts # Common utility functions
73+
│ ├── middleware.ts # Next.js middleware (auth, etc.)
74+
│ ├── next.config.ts # Next.js configuration
75+
│ ├── package-lock.json
76+
│ ├── package.json # Frontend dependencies and scripts
77+
│ ├── postcss.config.mjs
78+
│ ├── public # Static assets
79+
│ ├── schema.d.ts # Generated type definitions
80+
│ ├── tsconfig.json
81+
│ ├── types # TypeScript type definitions
82+
│ └── utils # Frontend utility functions
83+
├── package-lock.json
84+
├── package.json
85+
├── spec.json # API specification (generated by script)
86+
└── tsconfig.json # Root TypeScript configuration
87+
88+
```
89+
90+
### Running the App
91+
To deploy the app using Docker Compose run one of the following commands:
92+
```bash
93+
MODE="dev" LOG_VOLUME_MOUNT="./backend/log" docker compose up --build --watch # in dev more
94+
MODE="prod" LOG_VOLUME_MOUNT="./backend/log" docker compose up --build --watch # in production mode
95+
```
96+
97+
This will mount both the frontend and backend. `LOG_VOLUME_MOUNT` can be changed to redirect runtime logging. Note that running the backend in dev mode requires your local Supabase to be running - see [Database Management](#database-management) below for instructions.
98+
99+
If you want to run only the backend:
100+
```bash
101+
cd backend
102+
bun run dev # dev mode
103+
# OR
104+
bun run start # prod mode
105+
```
106+
107+
If you want to run only the frontend
108+
```bash
109+
cd frontend
110+
bun run dev # dev mode
111+
# OR
112+
bun run start # prod mode
113+
```
114+
115+
The backend will be available at [localhost:3001](http://localhost:3001/) and the frontend at [localhost:3000](http://localhost:3000/)
116+
117+
118+
### Database Management
119+
120+
We use [Supabase](https://supabase.com/) as a PostgreSQL development platform to manage our databases combined with [TypeORM](https://typeorm.io/).
121+
122+
To get a Supabase instance running locally, install the Supabase CLI, make sure your Docker engine is running, and run the following commands:
123+
```bash
124+
cd backend/
125+
bun run supabase start
126+
```
127+
128+
See your local Supabase studio at localhost:54323
129+
130+
To migrate your local DB to match the state of prod/git, run:
131+
```bash
132+
bun run migration:dev
133+
```
134+
135+
To run a migration on production (use this command with caution!), run:
136+
```bash
137+
bun run migration:prod
138+
```
139+
140+
To revert a migration in either environment, run:
141+
```bash
142+
bun run migration:dev:revert
143+
# OR
144+
bun run migration:prod:revert
145+
```
146+
147+
To stop your local instance of Supabase, run:
148+
```bash
149+
bun run supabase stop
150+
```
151+
152+
See [MIGRATION_TUTORIAL.md](./backend/supabase/MIGRATION_TUTORIAL.md) for more information about managing migrations with TypeORM.
153+
154+
### Type Generation
155+
We use OpenAPI documentation to generate types for the layer between the frontend and the backend for consistency. The development process should be as follows:
156+
157+
1. Make changes to an api endpoint in the backend.
158+
2. Update the OpenAPI routes in the associated file in the `/openapi` module.
159+
3. From the root directory, run `bun run gen-types` or `bun run g` to generate new `spec.json` and `schema.d.ts` files.
160+
4. In the `types` folder in the frontend, update imports from the `schema.d.ts` as necessary and use the types in the frontend.
161+
162+
This ensures consistent type expectations for a safe contract between the frontend and the backend.

‎backend/supabase/MIGRATION_TUTORIAL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
We are using a Supabase-hosted Postgres database. Our schema is relational and we handle changes by making migration scripts so that we have a changelog of the database schema history. Because we are using TypeORM a lot of this work is done for you!
44

5+
TypeORM will read the current state of your local database and the entities in the codebase and find the changeset between the two (any columns, tables, constraints, etc. that are different). Using the changeset, it generates a migration that, when run, will modify your local DB to match the state of the entities in the code. **Note that you should run all migrations before generating new ones to avoid duplication of migration scripts/errors in deployment**
6+
57
The following pathway allows you to make and test schema changes locally via migration script without affecting the shared database until you're ready. More information on local development best practices can be found in the [Supabase docs](https://supabase.com/docs/guides/cli/local-development). **Note that running the DB locally requires Docker to be installed and running.**
68

79
0. Install the Supabase CLI by following directions [here](https://supabase.com/docs/guides/local-development/cli/getting-started?queryGroups=access-method&access-method=postgres&queryGroups=platform&platform=macos).

0 commit comments

Comments
 (0)