Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/codegallantx/civictrack


https://github.com/codegallantx/civictrack

Last synced: 12 days ago
JSON representation

Awesome Lists containing this project

README 

        
# CivicTrack Code Documentation



**Project Overview**  

CivicTrack is an open-source platform developed with Next.js and styled using Tailwind CSS, aimed at enhancing political transparency in African communities. This project provides users with a comprehensive, accessible database of politicians, their roles, achievements, and portfolios. CivicTrack uses JSON files for data storage, enabling easy maintenance, portability, and data handling without a traditional database setup.



**Technologies Used**  

- **Framework**: Next.js

- **Styling**: Tailwind CSS

- **Other**: AOS

- **Data Storage**: JSON files for structured, local data handling.



---



## Folder Structure



- **`/app/components`**  

  Contains reusable React components such as `Header`, `Footer`, `Hero`, `Banner`, `PolitcianCards`, `FeaturedPortfolios`, `PortfolioList`, `FilterSidebar`, `PortfolioFilter`, and `Profile`. Each component is modular and styled with Tailwind CSS, providing consistency across the application.



- **`/app/data`**  

  Houses JSON files for storing politician and portfolio data (`politicians.json` and `portfolio.json`). This approach avoids the need for a database and facilitates data updates and retrieval.



- **`/app/politicians/page.js`**  

  Contains pages related to the listing, filtering, and detailed view of politicians. The files here define the routes, structure, and data-fetching logic for displaying politicians’ information.



---



## Key Components



### 1. **Header**  

  **File**: `components/Header.js`  

  **Purpose**: Provides a consistent navigation bar across all pages, containing links to the main sections of the application. This component is styled with Tailwind CSS and positioned at the top of each page to ensure easy navigation and brand consistency.



### 2. **Footer**  

  **File**: `components/Footer.js`  

  **Purpose**: Displays site-wide footer information, including navigation links, social media, and other essential information. The footer maintains a cohesive look across pages, promoting a consistent brand experience.



### 3. **Hero**  

  **File**: `components/Hero.js`  

  **Purpose**: Serves as the landing section on the homepage. The Hero component includes a call-to-action with links to view politician data or start exploring CivicTrack. It adapts for mobile and larger screens, centering content on mobile and aligning left on desktop for a dynamic user experience.



### 4. **Banner**  

  **File**: `components/Banner.js`  

  **Purpose**: Displays breadcrumb navigation and contextual information on specific pages, enhancing user experience by allowing users to navigate back to the main list or previous sections efficiently.



### 5. **PoliticianCards**  

  **File**: `components/PoliticianCards.js`  

  **Purpose**: A reusable card component that displays summarized information for each politician. Each card includes the politician's photo, name, role, and short bio, with links to view more detailed information. This component is styled to be visually appealing and adaptable across screen sizes.



### 6. **FeaturedPortfolios**  

  **File**: `components/FeaturedPortfolios.js`  

  **Purpose**: Highlights key portfolios associated with notable politicians or projects on the homepage. This component showcases selected portfolios to provide quick insights and draw users' attention to impactful projects.



### 7. **PortfolioList**  

  **File**: `components/PortfolioList.js`  

  **Purpose**: Displays a comprehensive list of all portfolios, with options to filter, sort, or search. This component allows users to browse through portfolios efficiently and locate specific projects or initiatives relevant to their interests.



### 8. **FilterSidebar**  

  **File**: `components/FilterSidebar.js`  

  **Purpose**: Provides filtering functionality, allowing users to refine politician lists by name, role, and country. The `useEffect` hook is employed to dynamically apply filter criteria based on user inputs, making it easy to narrow down searches.



### 9. **PortfolioFilter**  

  **File**: `components/PortfolioFilter.js`  

  **Purpose**: A specialized filter component designed for portfolios, allowing users to filter by parameters such as status, budget, or related politician. This component enhances user experience by simplifying the process of locating specific types of portfolios.



### 10. **Profile**  

  **File**: `components/Profile.js`  

  **Purpose**: Displays a detailed view of a specific politician, including their biography, achievements, portfolio, and social media links. The Profile component organizes information in a user-friendly layout, allowing users to gain a comprehensive view of each politician's contributions and background.



---



## Pages



### **Homepage**  

**File**: `app/page.js`  

> **Description**: Introduces CivicTrack's mission and vision, displaying key components like the Hero section, featured politicians, and recent portfolios. The homepage is designed to engage users with CivicTrack's purpose, with calls-to-action to explore data or get started.



### **Politicians List Page**  

**File**: `app/politicians/page.js`  

> **Description**: Provides a comprehensive list of all politicians. The page integrates the `FilterSidebar` component for filtering by name, role, and country, allowing users to refine their search and explore specific individuals or groups. Politician data is sourced from `politicians.json`.



### **Politician Detail Page**  

**File**: `app/politicians/page.js`  

> **Description**: Displays detailed information about a specific politician based on their `id`. Users can view the politician’s biography, achievements, portfolios, and social media links. The Profile component is utilized here to present a cohesive, in-depth view of the selected politician.



### **Portfolio Detail Page**  

**File**: `app/politicians/portfolio/[id]/page.js`  

> **Description**: Shows detailed portfolio information for a specific project associated with a politician, identified by `id`. The page provides insights into project objectives, status, and progress metrics stored in `portfolio.json`.



### **Contact Page**  

**File**: `app/contact/page.js`  

> **Description**: Contains a contact form for users to reach out with inquiries, suggestions, or feedback. This page helps CivicTrack foster engagement by providing an accessible channel for communication with users.



### **About Page**  

**File**: `app/about/page.js`  

> **Description**: Provides background information about CivicTrack's purpose, mission, and values, highlighting the team and the platform's role in promoting political transparency. This page builds credibility and educates users on CivicTrack's goals.



### **Login Page**  

**File**: `app/login/page.js`  

> **Description**: Allows users to securely log in with their credentials. Styled with Tailwind CSS, this page provides error handling and links to the signup and forgot-password pages for additional support.



### **Signup Page**  

**File**: `app/signup/page.js`  

> **Description**: Contains a registration form for new users to create an account on CivicTrack. The page includes validation, guidelines, and a link to the login page to ensure a smooth onboarding process.



### **Forgot Password Page**  

**File**: `app/forgot-password/page.js`  

> **Description**: Helps users reset their password in case they have forgotten it. Users enter their email to receive a password reset link, enhancing account security and accessibility.



### **404 Page**  

**File**: `app/pages/404.js`  

> **Description**: A custom error page displayed when users access a non-existent route. Although not implemented, it offers a friendly message and a link back to the homepage, ensuring users can easily navigate back to the site.



--- 

## Data Management



**Politician Data (politicians.json)**  

Each entry in `politicians.json` represents a politician with fields such as:

- `id`: Unique identifier

- `name`: Politician’s name

- `position`: Role or title

- `party`: Affiliated political party

- `country` and `state`: Geographic details

- `achievements`: List of notable accomplishments

- `socialMedia`: Links to social media profiles



**Portfolio Data (portfolio.json)**  

This JSON file contains details of portfolios or projects associated with politicians:

- `id`: Unique identifier for each portfolio entry

- `responsiblePoliticianId`: Maps the portfolio to a specific politician

- `title`: Name of the project or portfolio

- `description`: Brief overview of the portfolio

- `status` and `budget`: Indicates project status and budget if applicable

- `relatedLinks`: Any additional resources or links related to the portfolio



---



## Helper Functions



- **Data Fetching**  

  Files like `app/politicians/portfolio/[id]/page.js` use helper functions (`fetchPoliticians` and `fetchPortfolio`) to read JSON data from `/data`. These helper functions employ `fs.readFileSync` to load and parse JSON data, creating a mock database-like experience with static files.



- **Filtering Logic**  

  The `FilterSidebar` component uses the `useEffect` hook to dynamically apply filters based on user input (name, role, country). This helps narrow down the politicians’ list according to specific search criteria.



---



## Styling



All components and pages utilize Tailwind CSS, enabling rapid styling and responsive design. Tailwind’s utility-first approach ensures that styling remains consistent and adjustable for different screen sizes without extensive custom CSS.



**Examples of Tailwind Usage**:

- **Responsiveness**: Classes like `lg:w-3/5` and `md:text-5xl` ensure components adapt to different screen widths.

- **Color & Backgrounds**: `bg-gray-900`, `text-white`, and custom color hex codes provide a cohesive theme aligned with CivicTrack’s branding.



---



## API Documentation (Future Scope)



The current implementation uses JSON files, but future development could involve RESTful API endpoints for CRUD operations. APIs could allow:

- **GET** requests to retrieve politician and portfolio data.

- **POST/PUT** requests to add or update politician information.

- **DELETE** requests for managing data removal.



---



## Contribution Guidelines



Contributions are welcome! For consistency, please ensure:

1. **Code Quality**: Follow ES6 syntax and Next.js best practices.

2. **Styling**: Use Tailwind CSS classes for consistency.

3. **Testing**: Include testing for critical components if possible.



**For any questions or suggestions, please contact the project maintainers.**