Chronovos

Chronovos is a full‑stack historical timeline application that lets users explore historical events, log in via OAuth (Google/GitHub), and create public profiles that display a unique profile name and karma. The backend (Express) serves API endpoints and static content, while the frontend (React) provides a dynamic landing page, timeline, and profile management interface.

Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Usage
• Project Structure
• Environment Variables and Git Ignore
• Current Status
• Remaining Tasks
• Contributing
• License

Overview

Chronovos allows users to:

• Authenticate via OAuth (Google and GitHub).
• Create and update a public profile with a unique profile name, avatar, bio, and karma.
• Browse a historical timeline of events.
• Vote on events and track karma (stored in the profiles table).

Features

• OAuth Authentication: Login via Google or GitHub.
• User Profiles: Separate profile management with public information and karma.
• Dynamic Timeline: Browse historical events across eras and regions.
• Dockerized Environment: All services (frontend, backend, database) run in Docker containers.
• API Endpoints: Built with Express for authentication, profile management, and event data.

Prerequisites

• Docker
• Docker Compose
• A GitHub account (repository will be private)
• Node.js (for local development, if needed)

Installation

1. Clone the Repository:

   git clone git@github.com:moonwalkwoods/chronovos.git
   cd chronovos

2. Set Up Environment Variables:

   In the backend directory, create a file named .env with the following content (update with your actual values):

   PORT=5000
   DATABASE_URL=postgres://chronovos_user:chronovos_password@db:5432/chronovos_db
   JWT_SECRET=your_generated_secret
   NODE_ENV=development
   GOOGLE_CLIENT_ID=your_google_client_id
   GOOGLE_CLIENT_SECRET=your_google_client_secret
   GITHUB_CLIENT_ID=your_github_client_id
   GITHUB_CLIENT_SECRET=your_github_client_secret
   

   Note: The .env file is excluded from Git tracking (see below).

3. Install Local Dependencies (Optional for Development):

   For the frontend:

   cd frontend
   npm install

   For the backend:

   cd ../backend
   npm install

Usage

Build and Run Services:

From the root directory (where docker-compose.yml is located), run:

docker-compose up --build

• Backend: Runs on port 5000
• Frontend: Runs on port 3000
• Database: PostgreSQL runs on port 5432

Access the Application:

• React Frontend (Landing Page, Timeline, Profile): http://localhost:3000
• Express Backend (API Endpoints): http://localhost:5000

Authentication Flow:

1. Navigate to the login page on the frontend (/login) to select your OAuth provider.
2. The OAuth callback is handled on the backend at /auth/google/callback or /auth/github/callback, and upon successful authentication, the user is redirected to http://localhost:3000/profile.
3. On the profile page, users can create or update their public profile. Their profile data (including karma) is stored in the profiles table.

Project Structure

chronovos/
├── backend/
│   ├── config/
│   │   └── passport.js
│   ├── controllers/
│   │   ├── authController.js
│   │   ├── profileController.js
│   │   └── eventController.js
│   ├── migrations/
│   │   ├── 001_create_events_table.sql
│   │   ├── 002_create_people_table.sql
│   │   ├── 003_create_tags_table.sql
│   │   ├── 004_create_regions_table.sql
│   │   ├── 005_create_event_tags_table.sql
│   │   ├── 006_create_event_regions_table.sql
│   │   ├── 007_create_person_tags_table.sql
│   │   ├── 008_create_person_regions_table.sql
│   │   ├── 009_create_users_table.sql
│   │   ├── 010_create_sources_table.sql
│   │   └── 011_create_profiles_table.sql
│   ├── routes/
│   │   ├── authRoutes.js
│   │   ├── profileRoutes.js
│   │   └── eventRoutes.js
│   ├── utils/
│   │   └── db.js
│   ├── .env            # Not tracked in git
│   └── index.js
├── frontend/
│   ├── public/
│   │   ├── index.html
│   │   └── default.conf   # Custom Nginx configuration for client-side routing
│   ├── src/
│   │   ├── components/
│   │   │   └── NavBar.js
│   │   ├── pages/
│   │   │   ├── LandingPage.js
│   │   │   ├── LoginPage.js
│   │   │   ├── TimelinePage.js
│   │   │   └── ProfilePage.js
│   │   ├── App.js
│   │   └── utils/
│   │       └── apiClient.js
│   └── Dockerfile
├── docker-compose.yml
└── .gitignore

Environment Variables and Git Ignore

• .env: This file contains sensitive configuration (OAuth secrets, database URL, etc.) and should not be tracked.

• .gitignore: Your repository should include a .gitignore file in the root with entries like:

# Node modules
node_modules/

# Environment variables
.env

# Logs
*.log

# Build directories
/build

# Editor history or temporary files
.history/

Current Status

Backend:

• OAuth authentication (Google & GitHub) is set up.
• Users are stored in the users table.
• Profiles are stored in the profiles table, with a one-to-one relationship to users.
• Basic endpoints for authentication and profile management are implemented.

Frontend:

• A landing page, login page, mock timeline page, and profile page have been implemented.
• React Router is configured to handle navigation between pages.
• Custom Nginx configuration is in place to handle client-side routes.

Dockerization:

• The backend, frontend, and database are all containerized using Docker Compose.

Remaining Tasks

Backend:

• Expand CRUD endpoints for events and people.
• Implement voting and source validation endpoints.
• Add comprehensive error handling, logging, and tests.

Frontend:

• Fully integrate backend API endpoints (events, profiles, votes, etc.).
• Enhance UI/UX and responsiveness.
• Implement state management (e.g., Context API or Redux) for authentication and user data.
• Add timeline filtering, search, and additional features.

Deployment & Security:

• Configure production-ready environment variables and secure session or JWT management.
• Write comprehensive documentation and tests.

Contributing

Feel free to fork this repository and submit pull requests. For major changes, please open an issue to discuss what you would like to change.

License

This project is licensed under the MIT License.

How to Put This on GitHub

1. Initialize Git (if not already done):

   git init

2. Add Files and Commit:

   git add .
   git commit -m "Initial commit of Chronovos project"

3. Create a New Private Repository on GitHub:

   • Log in to GitHub with your account (moonwalkwoods).
   • Create a new repository named chronovos and set it to private.
   • Do not initialize it with a README since you already have one.

4. Add Remote and Push:

   git remote add origin git@github.com:moonwalkwoods/chronovos.git
   git push -u origin main