Site Architecture

Guide: https://github.com/hackforla/website/wiki/Hack-for-LA's-Site-Architecture

Civic Tech Index (CTI) uses React, a JavaScript library for building user interfaces, to generate the CTI website. One sentence summary of site architecture.

This guide provides a description of the folders and files in the Civic Tech Index repository and how to work with them. Helpful documentation if you're new to insert technology or front-end development:

Contents:

1. Repository Overview
   1. Configuration Files
   2. React Pages
   3. React Components
   4. Assets
   5. [Cypress / Testing] ()
   6. [Material-UI] ()
   7. [ESLint / Prettier] ()
   8. Pages
   9. Redirections
2. Projects
3. Organizations
4. Guide Pages
5. Styling
6. API Endpoints

Repository Overview

All components and pages that make up the site are located in src/, so that will be the "root" reference in this Overview description. The entry point into the site application is index.js, which applies Google Analytics tracking through GA4React and Material UI styling theme through createMuiTheme (along with importing theme-mui.js). Site-wide styling that does not belong in the theme is defined in styles.js. The actual site application is defined in the App component in App.js.

The App component imports a Layout that consists of a Header, the current page being displayed, and a Footer. Navigation menu structure in the Header and Footer is defined in navigation.js. The other major part of App is list of routes that provides info on how to navigate to all pages on the site. App also contains cookie popup functionality.

Any components that are used in multiple places throughout the site or are part of the general site layout are in components/. Components that make up the pages of the site are reside in pages/.

Configuration Files

React Pages

React Components

Assets

Cypress / Testing

Material-UI

ESLint / Prettier

Pages

Home page

Purpose: current home page that will be the landing page at site launch

Path: src/pages/Home

Structure:

• index.js is the parent file that contains its own style section and Home, MarketingSection, and CallToAction components
• sections subdirectory contains NotableUsersSection.js and TrendingTopicsSection.js components
• There is a notableUsers list that is defined in NotableUsersSection.js that contains info for CTI contributor orgs
• index.js imports NotableUsersSection and TrendingTopicsSection. It also imports GetStartedCard from src/components
• Home component contains all of the home page and displays the following components from top to bottom: MarketingSection, CallToActionSection, NotableUsersSection, TrendingTopicsSection, GetStartedCard

How to Add Your Project

Purpose: It shows the steps how to add topic tags to your project.

Path: src/pages/HowToAdd

Structure:

• HowToAdd component in the main file index.js, which contains its own style section and ImageComponent component, SettingsGearIcon component.
• ImageComponent component in src/components uses CardMedia Material UI component for displaying the images.
• SettingGearIcon component in src/components uses svg which is used to define vector-based-graphics and path is an element in svg library which defines a path that starts from a position and ends to a particular position. The path element uses attribute d which uses M which is used for moving a point to a certain location.

About page

Purpose: provides information on the organization's project

Path: src/pages/About

Structure:

• About is the parent component that is exported to App.js to render this page in the DOM.
• index.js is the parent file containing formatting and an object for mapping the images of the page
• A Grid component contains an iframe slideshow explaining various aspects of the project
• styles.js contains the styling for the page

Header component

Purpose: provides site navigation Links and subLinks in two display sizes

Path: src/components/Header

Structure:

• Header is the parent component exported from the index.js file contained within the Header folder.
• Header is exported to the Layout component found under src/components/common/Layout.js where it is exported using withRouter from react-router-dom. The Layout component wraps the Switch component imported from the react-router-dom package in the App component which handles the routing in src/App.js.
• The Header component is broken down into several smaller components with separate files: index, HeaderLarge, HeaderSmall, DropdownList, SearchContainer, NavLink and NavSublink. Several files make use of the navigation array exported from the src/navigation.js file. The Header folder also contains a separate styles.js sheet which provides styling to each of the components.
• index.js exports the Header component as default and is also where the switch between large and small displays is handled utilizing the Hidden component from the mui library.
• HeaderLarge feeds the values to the NavLink and NavSublink components from the navigation array via the .map method. It also houses the image link of the CTI logo to the landing page and a button link to the Search Projects screen.
• HeaderSmall contains the same links to search and the landing page as HeaderLarge, as well as passing values using the navigation array, but handles the display via a hamburger button allowing for visible or hidden links.
• SearchContainer is a component that exports a button link to Search Projects screen.
• DropdownList utilizes several mui packages to handle the functionality, display and style of the sublinks under each page heading.
• NavLink is a component built off the Link component from mui and the NavLink component (imported as 'NaviLink') from react-router-dom. The styling is built using hooks from the material-ui-popup-state package.
• The NavSublink component decides between external and internal links, with internal links being handled by a modified Link component (imported as RouterLink) from react-router-dom. Styling of the hover state of links in the large display dropdown menus are handled in this file.

Footer component

Purpose: provides site navigation links in three configurations at the foot of each page

Path: src/components/Footer

Structure:

• Footer is the parent component exported from the index.js file contained within the Footer folder.
• The Footer component is imported into the Layout component found under src/components/common/Layout.js where it is exported using withRouter from react-router-dom. The Layout component wraps the Switch component imported from the react-router-dom package in the App component which handles the routing in src/App.js.
• The Footer component is broken down into several smaller components with separate files: index, FooterLarge, FooterSmall, LinkList, DropdownList, SocialSection, SubscribeSection, and Annotation. Several files make use of the navigation array exported from the src/navigation.js file. The Footer folder also contains a separate styles.js sheet which provides styling to each of the components.
• index.js exports the Footer component and is also where the switch between large and small displays is handled utilizing the Hidden component from the mui library.
• FooterLarge feeds values to the LinkList component from the navigation array via the .map method, which is used for medium and larger displays. It also houses the large display versions of the SocialSection and the SubscribeSection. FooterSmall feeds the same links as FooterLarge, only passes them to the DropdownList component which is designed for small and extra small displays. It uses the small display versions of the SocialSection and the SubscribeSection. Both DropdownList`` and LinkListcreate custom links built off theLinkcomponent from thereact-router-dom``` library.
• SocialSection is a component that houses links for the Civic Tech Index social media sites.
• The SubscribeSection component uses axios to add users’ email addresses to the CTI database.
• The Annotation is a simple component providing a message at the bottom of the footer as well as links to CTI’s GitHub page and privacy policy.

FAQ page

Purpose: provides the list of frequently asked questions and their corresponding answers

Path: src/pages/Faq

Structure:

• Faq component is the main file it has index.js and useSearchFaq.js.
• index.js file has its own style section and it fetches the FAQ questions from axios.get(url) with a URL from an API endpoint which returns a response object and axios.post(url, requestBody) , with an URL from API endpoint and requestBody is passed which has question, answer and view_count attributes.
• index.js imports FAQCard Component from src/components and SearchBar from /SearchProjects/SearchBar.
• FAQCard component has accordianSection.js which has its own style section and it uses material UI accordion component which shows and hide sections of content on a page and index.js imports accordianSection.js which is used to display the Faq questions and answers and it also uses Pagination material UI component for displaying the Faq questions page wise.
• SearchProjects folder from src/pages/ is the main file and it has SearchBar.js which has its own style section and search bar component implemented for displaying the search bar on header.

Contact Us Page

Purpose: provides contact form for collecting the contact information.

Path: src/pages/Contact

Structure:

• Contact component is the main file and it has index.js.
• index.js file has its own style section and imports GenericHeaderSection from src/components which is used for displaying mainTitle,
  children and breadCrumbLinks.
• index.js file uses CardMedia component which embeds google docs for displaying the contact form.

Donate Page

Purpose: Provides information on how to make a donation as well as a link to the Code for America donation form.

Path: src/pages/Donate

Structure:

• Donate is the exported component from the main file index.js contained within the Donate folder that contains the entire view for the Donate page.
• index.js is the file that contains the functionality of the Donate component. It is formatted using @mui’s Grid component and draws its styling from the styles.js file. The file imports GenericHeaderSection from src/components which is used for displaying mainTitle, children and breadCrumbLinks through props. BottomCallToAction which links to the Contact page.
• Thestyles.js file contains the styling for the Donate component and imported by the index.js file.

Civic Tech Organizations

Purpose: It displays the unaffiliated, affiliated organizations and index contributors.

Path: src/pages/Contributors

Structure:

• index.js is the main file which imports NavBreadcrumbs , TitleSection and GetStartedCard all from /components and OrganizationSearch , Affiliated and UnaffiliatedOrganizations from /Contributors.
• NavBreadcrumbs in /components is used for displaying the navbreadcrumbs.
• TitleSection in /components for displaying the title of the page.
• GetStartedCard in /components for displaying the bottom section of the page.
• OrganizationSearch in /Contributors is used for searching affiliated and unaffiliated organizations.
• UnaffiliatedOrganizations component in /Contributors is used for displaying unaffiliated organizations.
• Affiliated component in /Contributors is used for displaying the affiliated organizations, it also imports AffiliatedOrganizations which is used to filtering the parent and child data and displaying on the page.

Collaborate with Us

Purpose: It displays the ways we can collaborate with Civic Tech Index project.

Path: src/pages/Collaborate

Structure:

• Collaborate component is the main component and it has index.js, LeftTextRightImage and RightTextLeftImage component.
• index.js file imports GenericHeaderSection, BottomCallToAction , LeftTextRightImage and RightTextLeftImage component.
• GenericHeaderSection from src/components which is used for displaying mainTitle, children and breadCrumbLinks.
• BottomCallToAction from src/components which is used for displaying footer text and button text.
• LeftTextRightImage from src/Collaborate is used for displaying the text on left and image on right component on the page.
• RightTextLeftImage from src/Collaborate is used for displaying the right text and image on left component on the page.

Redirections

Github-related folders

Projects

Organizations

Guide Pages

Styling

Why Sass?

Sass Basics Summary

Styling Files

Main.scss and Normalize.scss Files

Components

Elements

Layouts

Variables

API Endpoints