OpenCap Stack 🚀

OpenCap Stack is a comprehensive MERN stack application designed to manage stakeholders, share classes, documents, activities, notifications, equity simulations, tax calculations, and financial reporting. The project follows a Test-Driven Development (TDD) approach to ensure code quality and reliability and is fully aligned with the Open Cap Table Alliance (OCTA) schema.

Development Workflow 📝

This project follows the Semantic Seed Venture Studio Coding Standards (SSCS) which emphasizes:

• Structured Backlog Management with proper story IDs (OCAE-XXX, OCDI-XXX format)
• Test-Driven Development (TDD) with Red-Green-Refactor cycle
• Consistent Branch Naming (feature/OCAE-XXX, bug/OCAE-XXX, chore/OCAE-XXX)
• Daily Commits with proper prefixes (including "WIP:" for work in progress)
• Pull Request Process that maintains traceability to backlog items

For detailed workflow guidelines, see SSCS_Workflow_Guide.md.

Installation 🛠️

Follow these steps to set up the project on your local machine:

Prerequisites ✅

• Node.js (v14 or higher)
• MongoDB
• Docker and Docker Compose (for containerized development)
• Git

Clone the Repository 📂

git clone https://github.com/Open-Cap-Stack/opencap.git
cd opencap

Install Dependencies 📦

npm install

Set Up Environment Variables 🔐

Environment Variables

Create a .env file in the root directory and add the following:

MONGODB_URI=mongodb://mongo:27017/opencap
PORT=5000

Replace mongodb://mongo:27017/opencap with your MongoDB connection string if it's different.

Running the Project ▶️

Start the Development Server 🌐

npm start

This command starts the server on http://localhost:5000.

Start the Development Server 🔄

For automatic restarts on code changes, use:

npm run dev

Running with Docker 🐳

For a containerized development environment:

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Running Tests with Docker 🧪

docker-compose -f docker-compose.test.yml up --build

This will run all tests in a containerized environment, ensuring consistent test results across different development machines.

Running Tests 🧪

The project uses Jest for testing. To run the tests, use the following command:

npm test

This command runs all the test cases defined in the tests directory.

Code Coverage

We measure test coverage locally for development purposes only:

npm run test:coverage

Important Note: We do NOT integrate with Codecov or any other third-party coverage service. All coverage reporting should be performed locally and documented in pull requests when relevant.

CI/CD Pipeline 🔄

Our continuous integration and deployment pipeline focuses on:

1. Docker Hub: For container image storage and versioning
2. Digital Ocean: For deployment and hosting

Required GitHub Secrets

The following secrets are required for our CI/CD pipeline:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN
• DIGITALOCEAN_ACCESS_TOKEN

Deployment

We follow the deployment plan outlined in OpenCap_TestCoverage_DigitalOceanDeployment.md.

Resource Management Best Practices 🔧

To maintain codebase integrity and avoid conflicts:

1. Verify Existing Docker Resources:

   docker ps -a        # Check existing containers
   docker volume ls    # Check existing volumes

2. Check Existing Files and Directories:

   ls -la [directory]  # List directory contents
   find . -name "pattern"  # Find files matching pattern

3. Review Configurations: Always check current configuration before making changes

4. Database Schema Changes: Analyze existing schemas before modifications

These practices prevent duplication, conflicts, and ensure proper integration with the existing codebase.

API Endpoints 📡

Here are the primary API endpoints for the project:

Users 👤

• POST /api/users: Create a new user
• GET /api/users: Get all users
• GET /api/users/:id: Get a user by ID
• PUT /api/users/:id: Update a user by ID
• DELETE /api/users/:id: Delete a user by ID

Stakeholders 👥

• POST /api/stakeholders: Create a new stakeholder
• GET /api/stakeholders: Get all stakeholders
• GET /api/stakeholders/:id: Get a stakeholder by ID
• PUT /api/stakeholders/:id: Update a stakeholder by ID
• DELETE /api/stakeholders/:id: Delete a stakeholder by ID

Communication API 💬

• POST /api/communications: Create a new communication
• GET /api/communications: Get all communications
• GET /api/communications/:id: Get a communication by ID
• PUT /api/communications/:id: Update a communication
• GET /api/communications/threads/:threadId: Get communications by thread ID
• POST /api/communications/threads: Create a new thread

SPV (Special Purpose Vehicle) API 🏢

• POST /api/spv: Create a new SPV
• GET /api/spv: Get all SPVs
• GET /api/spv/:id: Get an SPV by ID
• PUT /api/spv/:id: Update an SPV
• GET /api/spv/status/:statusId: Get SPVs by status

SPV Asset API 💰

• POST /api/spv-assets: Create a new SPV asset
• GET /api/spv-assets: Get all SPV assets
• GET /api/spv-assets/:id: Get an SPV asset by ID
• PUT /api/spv-assets/:id: Update an SPV asset
• POST /api/spv-assets/:id/valuation: Add a valuation to an SPV asset

Compliance Check API ✓

• POST /api/compliance-checks: Create a new compliance check
• GET /api/compliance-checks: Get all compliance checks
• GET /api/compliance-checks/:id: Get a compliance check by ID
• PUT /api/compliance-checks/:id: Update a compliance check

Tax Calculator API 📊

• POST /api/taxCalculations: Create a new tax calculation
• GET /api/taxCalculations: Get all tax calculations
• GET /api/taxCalculations/:id: Get a tax calculation by ID
• PUT /api/taxCalculations/:id: Update a tax calculation

Share Classes 🏦

• POST /api/share-classes: Create a new share class
• GET /api/share-classes: Get all share classes
• GET /api/share-classes/:id: Get a share class by ID
• PUT /api/share-classes/:id: Update a share class by ID
• DELETE /api/share-classes/:id: Delete a share class by ID

Documents 📄

• POST /api/documents: Create a new document
• GET /api/documents: Get all documents
• GET /api/documents/:id: Get a document by ID
• PUT /api/documents/:id: Update a document by ID
• DELETE /api/documents/:id: Delete a document by ID

Activities 📋

• POST /api/activities: Create a new activity
• GET /api/activities: Get all activities
• GET /api/activities/:id: Get an activity by ID
• PUT /api/activities/:id: Update an activity by ID
• DELETE /api/activities/:id: Delete an activity by ID

Notifications 🔔

• POST /api/notifications: Create a new notification
• GET /api/notifications: Get all notifications
• GET /api/notifications/:id: Get a notification by ID
• PUT /api/notifications/:id: Update a notification by ID
• DELETE /api/notifications/:id: Delete a notification by ID

Equity Simulations 📊

• POST /api/equity-simulations: Create a new equity simulation
• GET /api/equity-simulations: Get all equity simulations
• GET /api/equity-simulations/:id: Get an equity simulation by ID
• PUT /api/equity-simulations/:id: Update an equity simulation by ID
• DELETE /api/equity-simulations/:id: Delete an equity simulation by ID

Tax Calculations 💰

• POST /api/tax-calculations: Create a new tax calculation
• GET /api/tax-calculations: Get all tax calculations
• GET /api/tax-calculations/:id: Get a tax calculation by ID
• PUT /api/tax-calculations/:id: Update a tax calculation by ID
• DELETE /api/tax-calculations/:id: Delete a tax calculation by ID

Financial Reporting 📈

• POST /api/financial-reports: Create a new financial report
• GET /api/financial-reports: Get all financial reports
• GET /api/financial-reports/:id: Get a financial report by ID
• PUT /api/financial-reports/:id: Update a financial report by ID
• DELETE /api/financial-reports/:id: Delete a financial report by ID

Project Structure 🗂️

The project structure is organized as follows:

opencap/
├── controllers/       # Controllers for handling API requests
├── models/            # Mongoose models
├── routes/            # API routes
├── __tests__/         # Test cases (unit, integration)
├── docs/              # Project documentation
├── dags/              # Airflow DAGs for data pipelines
├── .env               # Environment variables
├── .github/           # GitHub workflows for CI/CD
├── docker-compose.yml # Docker compose configuration
├── .gitignore         # Files to ignore in Git
├── CODE_OF_CONDUCT.md # Contributor code of conduct
├── package.json       # Project metadata and dependencies
├── README.md          # Project documentation

Contributing 🤝

Contributions are welcome! This project follows the Semantic Seed Venture Studio Coding Standards (SSCS) with a Test-Driven Development (TDD) approach. All contributions should adhere to these standards for consistent workflow and code quality.

Code of Conduct 📝

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please read the CODE_OF_CONDUCT.md for details on our code of conduct.

Guidelines for Contributing 📝

1. Fork the repository:

   git fork https://github.com/Open-Cap-Stack/opencap.git

2. Create a new branch following SSCS naming conventions:

   git checkout -b feature/OCAE-XXX  # For new features
   git checkout -b bug/OCAE-XXX      # For bug fixes
   git checkout -b chore/OCAE-XXX    # For maintenance tasks

3. Write tests first (Red Tests):

   • Write tests that demonstrate the functionality is NOT already present.
   • Make a WIP commit:

   git add .
   git commit -m "WIP: OCAE-XXX: Red Tests for feature description"

4. Implement code to pass the tests (Green Tests):

   • Write the minimum amount of code required to pass the tests.
   • Make a WIP commit when tests pass:

   git add .
   git commit -m "WIP: OCAE-XXX: Green Tests for feature description"

5. Refactor your code:

   • Refactor to improve code quality without changing functionality.
   • Re-run the tests and commit with a final message:

   git add .
   git commit -m "OCAE-XXX: Implement feature description"

6. Push your branch and create a pull request:

   git push origin feature/OCAE-XXX

   • Create a PR on GitHub with the story ID in the title.
   • Include story details in the description.
   • Mark the story as "Finished" in Shortcut.

7. Daily Commits Required:

   • Even for incomplete work, commit daily with "WIP:" prefix.
   • This ensures visibility and allows for collaboration.

For more detailed guidelines, refer to our SSCS_Workflow_Guide.md.

Submitting Changes 🚀

Follow these steps to submit your code changes:

1. Create a new branch:

   git checkout -b feature/{story-id}  # For features
   git checkout -b bug/{story-id}      # For bugs
   git checkout -b chore/{story-id}    # For chores

2. Make your changes:

   • Ensure your code follows the coding standards (see below).

3. Write failing tests:

   • Write tests that demonstrate the functionality is NOT already present.
   • Make a WIP commit:

   git add .
   git commit -m "WIP: Red Tests."

4. Implement code to pass the tests:

   • Make WIP commits as you go, and commit code when your tests are green:

   git add .
   git commit -m "WIP: Green Tests."

5. Refactor your code:

   • Refactor to improve code quality. Re-run the tests and commit:

   git add .
   git commit -m "Refactor complete."

6. Submit a pull request:

   git push origin feature/{story-id}  # Push your branch

   • Go to the repository on GitHub and create a pull request from your branch to the main branch.

7. Review process:

   • Review outstanding pull requests, comment on, approve and merge open pull requests, or request changes on any PRs that need improvement.

Coding Standards 🎨

Please follow these coding standards to maintain code quality and consistency:

• Indentation: Use 4 spaces for indentation.

• Naming Conventions:

  • Variables and functions: camelCase
  • Classes and components: PascalCase
  • Constants: UPPERCASE_SNAKE_CASE

• Comments:

  • Use JSDoc style comments for functions and classes.

Provide meaningful comments for complex code segments and functions.

• Document any public APIs and classes with clear explanations of their purpose and usage.

• Remove or update outdated comments as code changes.

• Code Structure:

  • Organize code into modules and components.
  • Keep functions small and focused on a single task.

• Lint: Ensure your code passes ESLint checks:

  npm run lint

• Testing:

  • Write unit tests using BDD-style frameworks like Mocha or Jasmine.

  • Follow the Arrange, Act, and Assert (AAA) pattern:

    it('should correctly add two positive numbers', () => {
      // Arrange
      const num1 = 5;
      const num2 = 7;
    
      // Act
      const result = add(num1, num2);
    
      // Assert
      expect(result).to.equal(12);
    });

  • Write integration tests to validate interactions between different parts of the application.

  • Write functional tests to validate the application's functionality.

License 📜

This project is licensed under the MIT License. See the LICENSE file for details.