Merge pull request #11 from Shanabunga/add-docs

Add Project, Repo & Architecture Documentation

Author: Shanabunga

README.md

@@ -1,15 +1,58 @@
-Welcome to your new dbt project!
+## Our dbt Project
+This repository consists of a [dbt](https://www.getdbt.com/) project that transforms raw data sources into clear, formatted models for Analytics.
 
-### Using the starter project
+To learn more about the overall architecture design & strategy can be found in our centralized handbook:
+- [Data Architecture Handbook](https://docs.google.com/document/d/1WmOnx_5QaGmo-kNWitd9jSEwvEnwqxiS0ZA1jmMV-v0/edit?usp=sharing)
 
-Try running the following commands:
-- dbt run
-- dbt test
+### Sources:
+Raw, unformatted data loaded directly from source systems using various data tools.
+- `nba_data` - The primary source of NBA statistics data captured from an API & loaded via Sling/Airbyte.
+    - Schema: `analytics.raw_nba_data`
+- `google_sheets` - Internally maintained reference sheets related to the project & loaded via Sling/Airbyte.
+    - Schema: `analytics.raw_google_sheets`
 
 
+### Environments:
+Transformed data models built via dbt with 3 distinct environments to enable a sustainable development workflow.
+- **Development**
+   - Schema: `analytics.dev_[your-name]`
+   - One per developer to avoid conflicts or overriding changes during development.
+- **CI**
+   - Schema: `analytics.ci`
+   - An isolated schema created specifically for testing Pull Request changes to ensure quality.
+- **Production**
+   - Schemas: 
+        - `analytics.staging`
+        - `analytics.warehouse`
+        - `analytics.marts`
+   - Separation by layer for easier navigation and permission management.
+
+### How to Get Started?
+1. Create your local development environment
+   - Use a local IDE (ex. VS Code), dbt Cloud or GitHub Codespaces
+2. Clone the current repo (or create a new one)
+   - Checkout the `main` branch and run `git pull` to sync changes
+3. Create a New Branch for your new changes
+   - First, run `git branch your_branch_name` to create a new branch
+   - Then run `git checkout your_branch_name` to switch to it
+4. Start developing!
+   - Commit & Sync all changes to your branch during development
+   - *IMPORTANT* - All changes should follow the team [Style Guide](_project_docs/style_guide.md)
+5. Create Pull Request
+   - When development is complete, Push your branch to GitHub & create a request
+   - Request peer reviews & confirm  automated CI jobs succeed
+6. Merge changes to the `main` branch
+   - Confirm automated post-merge jobs succeed
+7. Get latest changes in your local environment
+   - Checkout the `main` branch in your local terminal
+   - Run "git pull" to sync the latest version of the code
+8. Continue to develop & repeat the process
+
+### Notes
+- Provide any other important call-outs of platform-specific information here.
+
 ### Resources:
 - Learn more about dbt [in the docs](https://docs.getdbt.com/docs/introduction)
 - Check out [Discourse](https://discourse.getdbt.com/) for commonly asked questions and answers
 - Join the [chat](https://community.getdbt.com/) on Slack for live discussions and support
-- Find [dbt events](https://events.getdbt.com) near you
-- Check out [the blog](https://blog.getdbt.com/) for the latest news on dbt's development and best practices
+- Check out [the blog](https://blog.getdbt.com/) for the latest news on dbt's development and best practices

macros/_macros__definitions.yml

@@ -0,0 +1,5 @@
+version: 2
+
+macros:
+  - name: generate_schema_name
+    description: '{{ doc("generate_schema_name_description") }}'

macros/_macros__docs.md

@@ -0,0 +1,13 @@
+{% docs generate_schema_name_description %}
+This is a built-in dbt macro that changes the dataset name based on `target` and `+schema` config.
+
+* If `target` == `prod`, then models will deploy to separate datasets based on `+schema` config set in `dbt_project.yml`. For example:
+   * `staging`
+   * `warehouse`
+* For any non-`prod` deployment, all models will deploy to the default dataset as indicated in `profiles.yml`. For example:
+   * `dev_mkahan`
+   * `dev_jdoe`
+
+More information can be found at the dbt docs site [here](https://docs.getdbt.com/docs/building-a-dbt-project/building-models/using-custom-schemas#how-does-dbt-generate-a-models-schema-name)
+
+{% enddocs %}

models/marts/_marts__docs.md

@@ -0,0 +1,18 @@
+{% docs nba_games_detail_description %}
+A breakdown of metrics & other context related to individual `games`.
+
+This model is presented on a `game`-level granularity and built with reusability in mind. The expectations is that the data will be aggregated in various ways but access to the underlying data points will still be desired. Example aggregations include by date, team, conference, coach, etc.
+
+The metrics in this model include (but not limited to):
+* Total games played
+* Home/away scores
+* Point differentials
+* Home vs Away wins
+
+Other game & team related detail inslude (but not limited to):
+* Team Names
+* Head Coaches
+* General Managers
+* Day Info (Date, Weekday, Month)
+* Game Status (Regulation, Overtime)
+{% enddocs %}