Skip to content

Commit e235d08

Browse files
app-generatorapp-generator
committed
README Update DOCS
1 parent efeceb3 commit e235d08

File tree

1 file changed

+106
-118
lines changed

1 file changed

+106
-118
lines changed

‎README.md

Lines changed: 106 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,149 @@
11
# FastAPI Soft Dashboard
22

3-
Open-source starter powered by FastAPI on top of **[Soft UI Dashboard](https://github.com/app-generator/ct-soft-ui-dashboard-enh)** (free version).
4-
5-
> UI Kit: [Soft UI Dashboard](https://github.com/app-generator/ct-soft-ui-dashboard-enh) **v1.0.6-enh1**
3+
Open-source FastAPI starter provided by `AppSeed` op top of a modern `Bootstrap 5` design. Designed for those who like bold elements and beautiful websites, **Soft UI Dashboard** is ready to help you create stunning websites and webapps. **Soft UI Dashboard** is built with over 70 frontend individual elements, like buttons, inputs, navbars, nav tabs, cards, or alerts, giving you the freedom of choosing and combining.
64

75
<br />
86

97
> Product Roadmap
108
119
| Status | Item | info |
1210
| --- | --- | --- |
13-
| ❌ | **Up-to-date Dependencies** | - |
14-
| ❌ | **Best Practices** | This [guide](https://github.com/zhanymkanov/fastapi-best-practices) used as reference |
15-
| ❌ | **Simple, Intuitive Codebase** | [More info](https://github.com/app-generator/fastapi-soft-ui-dashboard/issues/1) |
16-
| ❌ | **UI Kit** | `Bootstrap 5`, `Dark-Mode` (persistent) |
17-
| ❌ | **Persistence** | `SQLite`, `MySql` |
18-
| ❌ | **Basic Authentication** | classic user/password |
19-
| ❌ | **OAuth** | `Github` & `Twitter` providers |
20-
| ❌ | **API** | Products & Sales (linked tables) |
21-
| | | GET Requests (public), `get/`, `get/id` |
22-
| | | Mutating requests (Create, UPD, DEL) (reserved for authenticated users) |
11+
| ✅ | **Up-to-date Dependencies** | - |
12+
| ✅ | **[Soft Dashboard Design](https://www.creative-tim.com/product/soft-ui-dashboard?AFFILIATE=128200)** | (Free Version) by `Creative-Tim` |
13+
| ✅ | **UI Kit** | `Bootstrap 5`, `Dark-Mode` (persistent) |
14+
| ✅ | **Persistence** | `SQLite`, `MySql` |
15+
| ✅ | **Basic Authentication** | classic user/password |
16+
| ✅ | **API** | Products & Sales (linked tables) |
17+
| | | GET Requests (public), `get/`, `get/id` |
18+
| | | Mutating requests (Create, UPD, DEL) (reserved for authenticated users) |
2319
| ❌ | **Docker** | Simple Setup (local usage) |
20+
| ❌ | **OAuth** | `Github` & `Twitter` providers |
21+
22+
<br />
2423

25-
> Something is missing? Submit a new `product feature request` using the [issues tracker](https://github.com/app-generator/fastapi-soft-ui-dashboard/issues).
24+
![Soft UI Dashboard - Open-source FastAPI starter provided by by AppSeed.](https://user-images.githubusercontent.com/51070104/175773323-3345d618-0e78-4c85-83fc-f495dc3f0bb0.png)
2625

2726
<br />
2827

29-
## How to used in `Docker`
28+
## Project Structure
29+
30+
> This application is composed of `3 basic parts` in the root folder.
3031
31-
> Development `Docker`
32+
- `src` provides the codebase for the main application.
33+
- `alembic` manages the DB database migration layer
34+
- `tests` stores the unit testing library.
3235

33-
- The docker-compose.yaml file is to be used for Development.
34-
- This particular docker-compose houses the `sqlite configuration`.
35-
- in the root folder, enter the following command (without the quotes):
36-
- `$ docker-compose up --build`.
36+
<br />
3737

38-
> Production Docker
39-
- The default docker-compose.yaml file is to be used for production.
40-
- This particular docker-compose houses the `mysql configuration`.
41-
- in the root folder, enter the following command (without the quotes): `docker-compose up`.
38+
## Manual Build
39+
40+
> Download the code
41+
42+
```bash
43+
$ git clone https://github.com/app-generator/fastapi-soft-ui-dashboard.git
44+
$ cd fastapi-soft-ui-dashboard
45+
```
4246

4347
<br />
4448

45-
## The manual build
49+
> Install modules via `VENV`
4650
47-
> This application is composed of `3 basic parts` in the root folder.
48-
1. src store the codebase for the main application.
49-
2. alembic stores the database migration library.
50-
3. tests stores the unit testing library.
51+
```bash
52+
$ python -m venv env
53+
$ source env/bin/activate
54+
$ pip install -r requirements.txt
55+
```
5156

52-
> The following are `steps on how to manually build the fastapi app`. All of the commands are to be entered in the root directory.
53-
1. create a virtual environment with the following command (always without the quotes): `python -m venv venv`
54-
2. activate the virtual environment, for linux/ubuntu: `source/bin/activate`, for windows `source/Scripts/activate`
55-
3. install the dependencies: `pip install -r requirements.txt`
56-
4. create a `.env` file, then copy and paste-in the contents of `.env.dist`, and fill in the configuration with your credentials.
57-
> setting the `debugging` config to `1` will start the app with sqlite, setting it to `0` will start the app with mysql.
58-
5. run the application: `uvicorn src.app:app --reload`
57+
<br />
5958

60-
> The following are `steps on how to run unit testing`.
61-
1. in the root directory: `pytest -v -s`
59+
> Create `.env` from `env.sample` - here is a sample
6260
63-
> The following are `steps on how to migrate the structure of the database`
64-
1. in the root directory: `alembic upgrade head`
65-
> instead of `head` a version id can be supplied.
61+
**Note:** Setting the `debugging` config to `1` will start the app with `SQLite`, setting it to `0` will start the app with `MySql`.
6662

67-
@ToDo
63+
```env
64+
DEBUGGING=1
6865
66+
DATABASE_HOSTNAME=localhost
67+
DATABASE_PORT=5432
68+
DATABASE_PASSWORD=somepassword
69+
DATABASE_NAME=somedbname
70+
DATABASE_USERNAME=mayberoot
6971
70-
```bash
71-
$ # All steps below
72+
SECRET_KEY=SUPER_SECRET_HERE
73+
ALGORITHM=HS256
74+
75+
ACCESS_TOKEN_EXPIRE_MINUTES=30
7276
```
7377

74-
Access the `app` section in the browser: `http://127.0.0.1:5000/`
78+
<br />
79+
80+
> Migrate the database (`create tables`)
81+
82+
```bash
83+
$ alembic upgrade head
84+
```
7585

7686
<br />
7787

78-
## ✨ Code-base structure
88+
> Start the app
7989
80-
@ToDo - The project structure (to be updated)
90+
```bash
91+
$ uvicorn src.app:app --reload
92+
```
8193

94+
At this point, the app runs at `http://127.0.0.1:8000/`.
95+
96+
<br />
97+
98+
## ✨ Codebase structure
99+
100+
The project is coded using a modular, intuitive structure as presented below:
82101

83102
```bash
84103
< PROJECT ROOT >
85-
|-- .github/ # Folder having github configurations
86-
| |-- workflows/ # Folder having github workflow configurations
87-
| |-- main.yml # Main workflow for automated unit testing/syntax check
88-
| |-- release.yml # Release workflow to release code when PR merged in main
89-
| |-- CODEOWNERS # List of codeonwers, special check can be made in repo settings
90-
| |-- PULL_REQUEST_TEMPLATE.md # PR template
91-
| |-- dependabot.yml # Dependabot configurations (optional)
92-
|-- docs/ # Folder to contain any helping docs
93-
| |-- api_examples.json # Example doc
94-
|-- scripts/ # Folder to contain any SQL scripts
95-
| |-- scripts.sql # Example script
96-
|-- src/ # Folder having all the python code
97-
| |-- models # Folder having all models
98-
| |-- custom/ # Folder for custom models
99-
| |-- db/ # Folder for database models
100-
| |-- product.py # Example file for product model
101-
| |-- sales.py # Example file for sales model
102-
| |-- request.py # File containing all request models
103-
| |-- response.py # File containing all response models
104-
| |-- routers/ # Folder for all FastAPI routes
105-
| |-- v1/ # Folder for v1 version
106-
| |-- auth/ # Folder for authentication routes
107-
| |-- auth_routes.py # File containing authentication routes for v1
108-
| |-- product_routes.py # File containing product routes for v1
109-
| |-- sales_routes.py # File containing sales routes for v1
110-
| |-- healthcheck.py # Base file for healthcheck for FastAPI
111-
| |-- helpers/ # Folder containing helper methods
112-
| |-- product_helpers.py # File having product related helper methods
113-
| |-- sales_helpers.py # File having sales related helper methods
114-
| |-- common_helpers.py # File having common helper methods
115-
| |-- database.py # File having database connection and methods
116-
| |-- cache.py # File having cache connection and methods
117-
| |-- decorators.py # File having decorators
104+
|
105+
|-- src/
106+
| |
107+
| |-- helpers/ # A simple app that serve HTML files
108+
| | |-- database.py # Define app routes
109+
| | |-- utils.py # Define app routes
110+
| |
111+
| |-- routers/ # Handles routes (all sections)
112+
| | |-- auth/ # Implements authentication routes
113+
| | |-- ui_routes.py
114+
| | |-- user_routes.py
115+
| |
118116
| |-- static/
119-
| |-- <css, JS, images> # CSS files, Javascripts files
120-
| |-- templates/ # Templates used to render pages
121-
| |-- includes/ # HTML chunks and components
122-
| |-- navigation.html # Top menu component
123-
| |-- sidebar.html # Sidebar component
124-
| |-- footer.html # App Footer
125-
| |-- scripts.html # Scripts common to all pages
126-
| |-- layouts/ # Master pages
127-
| |-- base-fullscreen.html # Used by Authentication pages
128-
| |-- base.html # Used by common pages
129-
| |-- accounts/ # Authentication pages
130-
| |-- login.html # Login page
131-
| |-- register.html # Register page
132-
| |-- home/ # UI Kit Pages
133-
| |-- index.html # Index page
134-
| |-- 404-page.html # 404 page
135-
| |-- *.html # All other pages
136-
| |-- app.py # Containing main method, project startup
137-
| |-- config.py # Containing Settings class for fetching configurations
138-
| |-- constants.py # Global constants
139-
| |-- exception_handlers.py # Global exception handling
117+
| | |-- <css, JS, images> # CSS files, Javascripts files
118+
| |
119+
| |-- templates/ # Templates used to render pages
120+
| | |-- includes/ # HTML chunks and components
121+
| | | |-- navigation.html # Top menu component
122+
| | | |-- sidebar.html # Sidebar component
123+
| | | |-- footer.html # App Footer
124+
| | | |-- scripts.html # Scripts common to all pages
125+
| | |
126+
| | |-- layouts/ # Master pages
127+
| | | |-- base-fullscreen.html # Used by Authentication pages
128+
| | | |-- base.html # Used by common pages
129+
| | |
130+
| | |-- accounts/ # Authentication pages
131+
| | | |-- login.html # Login page
132+
| | | |-- register.html # Register page
133+
| | |
134+
| | |-- home/ # UI Kit Pages
135+
| | |-- index.html # Index page
136+
| | |-- 404-page.html # 404 page
137+
| | |-- *.html # All other pages
138+
| |
139+
| models.py # Defines the models
140+
| config.py # Holds APP Configuration
141+
| __init__.py # Builds the FastAPI object
142+
| app.py # Bundles ALL resources
140143
|
141-
|-- tests/ # Folder having tests
142-
| |-- __init__.py # Containing test startup
143-
| |-- v1/ # Tests for version v1
144-
| |-- __init__.py
145-
| |-- test_v1.py # Containing tests for version v1
144+
|-- requirements.txt # App Dependencies
146145
|
147-
|-- .env.dist # Template for environment variables
148-
|-- .env # Actual environment variables file
149-
|-- .gitignore # File containing git ignore configurations
150-
|-- CHANGELOG.md # File containing change logs
151-
|-- LICENSE # File containing license information
152-
|-- Dockerfile # Docker file
153-
|-- Makefile # File containing make commands
154-
|-- README.md # README file
155-
|-- docker-compose.yaml # File to run docker along with other dependencies
156-
|-- requirements.txt # Python packages dependencies
157-
|-- package-lock.json # npm packages information
158-
|-- package.json # npm packages dependencies
146+
|-- .env # Inject Configuration via Environment
159147
|
160148
|-- ************************************************************************
161149
```

0 commit comments

Comments
 (0)