Product Requirements Document (PRD) for Open Cap Stack V2.0

[urbantech]

1. Overview

Product Name: Open Cap Stack V2.0
Purpose: The Open Cap Stack V2.0 aims to deliver a comprehensive API-based platform for managing corporate governance, capitalization, compensation, and investor relations, providing stakeholders with a seamless, secure, and user-friendly experience. The platform allows users to manage and track corporations, investors, securities, and portfolios, with a particular focus on compliance and transparency.

---

2. Goals and Objectives

1. Comprehensive API Coverage:

   • Develop APIs covering all functionalities required to manage corporations, compensation, investors, securities, and portfolios, including SPVs, convertible notes, certificates, and more.
   • Ensure the API follows a consistent naming convention and standard response structure.

2. User Experience:

   • Provide a user-friendly interface for administrators and stakeholders to interact with the system.
   • Implement detailed error messages and validation to enhance the user experience.

3. Security and Compliance:

   • Ensure that the platform complies with relevant regulations, including data privacy, financial reporting standards, and compliance for securities and SPVs.
   • Implement robust authentication and authorization mechanisms, including OAuth 2.0 and role-based access control (RBAC).

4. Scalability and Performance:

   • Design the system to handle a large number of API requests concurrently, especially for financial transactions and data management.
   • Optimize database queries and API response times to ensure quick data retrieval across all modules.

---

3. Key Features and Requirements

3.1. Corporations

• List Corporations:
  • API Endpoint: GET /api/v2/corporations
  • Description: Retrieve a list of corporations that a user has access to.
  • Response:

    {
      "corporations": [
        {
          "id": "611",
          "legalName": "MangoCart, Inc.",
          "doingBusinessAsName": "MangoCart",
          "website": "http://www.example.com/mangocart"
        }
      ],
      "nextPageToken": "ODMxMw=="
    }

3.2. Compensation

• Get Compensation Benchmark Attributes:

  • API Endpoint: GET /api/v2/compensation/benchmarks/attributes
  • Description: Retrieve all valid compensation benchmark attributes based on a corporation's plan.
  • Response:

    {
      "benchmarks_metadata": {
        "benchmarks_version_datetime": {
          "value": "2024-01-01T09:00:00.000000Z"
        }
      },
      "compensation_types": ["SALARY", "EQUITY_AS_FULLY_DILUTED_PERCENT"],
      "industries": ["All"],
      "percentiles": ["P25", "P50", "P75"],
      "post_money_valuation_buckets": ["10M to 25M", "50M to 100M"],
      "geo_adjustment_location": ["Dallas-Fort Worth-Arlington, TX", "New York-Newark-Jersey City, NY-NJ-PA", "San Francisco-Oakland-Hayward, CA"],
      "jobs": [
        {
          "job_area": "Engineering",
          "job_specialization": "Web Engineer",
          "job_levels": ["IC 2", "IC 3", "MGR 4", "MGR 5", "EX 10", "EX 11"]
        }
      ]
    }

• Get Compensation Benchmarks:

  • API Endpoint: GET /api/v2/compensation/benchmarks
  • Description: Retrieve all compensation benchmarks based on a corporation's compensation plan.
  • Response:

    {
      "access": {
        "access_level": "FULL_ACCESS",
        "access_reason": ""
      },
      "benchmarks_metadata": {
        "benchmarks_version_datetime": {
          "value": "2024-01-01T09:00:00.000000Z"
        }
      },
      "benchmarks": [
        {
          "post_money_valuation_bucket": "100M to 250M",
          "industry": "All",
          "geo_adjustment_location": "New York-Newark-Jersey City, NY-NJ-PA",
          "job_area": "Engineering",
          "job_specialization": "Web Engineer",
          "job_level": "IC 3",
          "benchmark_values": [
            {
              "compensation_type": "SALARY",
              "percentile": "P25",
              "benchmark": {
                "value": "100000"
              }
            }
          ]
        }
      ]
    }

3.3. Issuers

• List Issuers:

  • API Endpoint: GET /api/v2/issuers
  • Description: Retrieve a list of issuers.
  • Response:

    {
      "issuers": [
        {
          "id": "611",
          "legalName": "MangoCart, Inc.",
          "doingBusinessAsName": "MangoCart",
          "website": "http://www.example.com/mangocart"
        }
      ],
      "nextPageToken": "ODMxMw=="
    }

• Get Issuer:

  • API Endpoint: GET /api/v2/issuers/{issuerId}
  • Description: Retrieve details of a specific issuer.
  • Response:

    {
      "issuer": {
        "id": "611",
        "legalName": "MangoCart, Inc.",
        "doingBusinessAsName": "MangoCart",
        "website": "http://www.example.com/mangocart"
      }
    }

3.4. Investors

• List Firms:

  • API Endpoint: GET /api/v2/investors/firms
  • Description: Retrieve a list of investment firms.
  • Response:

    {
      "firms": [
        {
          "id": "7af7123a-2ee9-4e31-a173-54b8f9159426",
          "name": "Krakatoa Ventures"
        }
      ],
      "nextPageToken": "ODMxMw=="
    }

• List Funds:

  • API Endpoint: GET /api/v2/investors/firms/{firmId}/funds
  • Description: Retrieve the investment funds of a given investment firm.
  • Response:

    {
      "funds": [
        {
          "firm_id": "7af7123a-2ee9-4e31-a173-54b8f9159426",
          "id": "09051fa3-fe71-4613-9bfb-e5bfa396cfea",
          "name": "Krakatoa Ventures Fund I, L.P."
        }
      ],
      "nextPageToken": "ODMxMw=="
    }

• List Investments:

  • API Endpoint: GET /api/v2/investors/funds/{fundId}/investments
  • Description: Retrieve the company investments of a given investment fund.
  • Response:

    {
      "investments": [
        {
          "firmId": "7af7123a-2ee9-4e31-a173-54b8f9159426",
          "fundId": "09051fa3-fe71-4613-9bfb-e5bfa396cfea",
          "companyId": "bc495a05-bd5b-451e-bdfc-88eea3fccfe8",
          "legalName": "MangoCart, Inc.",
          "doingBusinessAsName": "MangoCart",
          "website": "https://example.com",
          "country": "USA",
          "stateOfIncorporation": {
            "value": "US-CA"
          }
        }
      ]
    }

I apologize for the oversight. The issue might be related to the nested JSON within the markdown not being closed correctly. Here’s the corrected version of item 3.5:

3.5. Securities

• List Certificates:
  • API Endpoint: GET /api/v2/securities/certificates
  • Description: Retrieve certificates issued by an investment company to a fund within a firm.
  • Response:

    {
      "certificates": [
        {
          "firmId": "0c481821-3bc8-42a5-94cd-a2c89d88429d",
          "firmName": "Krakatoa Ventures",
          "fundId": "6c26b46f-6515-4685-a438-9811c607788a",
          "fundName": "Krakatoa Ventures Fund I, L.P.",
          "companyId": "a44b42cb-d16a-4427-8dd2-d33083fb638a",
          "companyName": "Meetly",
          "currentStakeholderId": "11",
          "id": "143",
          "securityLabel": "CS-10",
          "shareClassId": "64",
          "shareClassName": "Common (certificated)",
          "issueDate": {
            "value": "2024-05-24"
          },
          "quantity": {
            "value": "1000.0"
          },
          "pricePerShare": {
            "currencyCode": {
              "value": "USD"
            },
            "amount": {
              "value": "50.0"
            }
          },
          "lastModifiedDatetime": {
            "value": "2024-08-22T21:51:23Z"
          },
          "canceledDate": {
            "value": "2024-08-25"
          },
          "terminationDate": {
            "value": "2024-09-15"
          }
        }
      ]
    }

3.6. Capitalization Tables

• Get Capitalization Table:
  • API Endpoint: GET /api/v2/capitalization-tables/{capTableId}
  • Description: Retrieve the capitalization table for a corporation as of a specific date.
  • Response:

    {
      "capTable": {
        "id": "53bd35b5-95d0-4185-96f6-1b748b69f8ea",
        "issuerId": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
        "asOfDate": "2024-01-01",
        "fullyDilutedShares": "2000000",
        "outstandingShares": "1500000",
        "cashRaised": "10000000",
        "shareClassSummaries": [
          {
            "shareClassID": "CS-10",
            "outstandingShares": "1000000",
            "fullyDilutedShares": "1200000",
            "cashRaised": "8000000"
          }
        ],
        "optionPoolSummaries": [
          {
            "optionPoolId": "OP-15",
            "shareClassId": "CS-10",
            "fullyDilutedShares": "500000",
            "outstandingEquityAwardDerivatives": "300000"
          }
        ],
        "warrantBlockSummaries": [
          {
            "warrantBlockId": "WB-01",
            "shareClassId": "CS-10",
            "fullyDilutedShares": "500000",
            "outstandingWarrants": "200000"
          }
        ],
        "noteBlockSummaries": [
          {
            "noteBlockId": "NB-03",
            "principal": "500000",
            "interest": "50000",
            "outstanding_debt": "550000"
          }
        ]
      }
    }

3.7. SPVs

• Create SPV:
  • API Endpoint: POST /api/v2/spvs
  • Description: Create a new Special Purpose Vehicle (SPV).
  • Request Body:

    {
      "Name": "New SPV",
      "Purpose": "Investment",
      "CreationDate": "2024-05-01",
      "Status": "Active",
      "ParentCompanyID": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
      "ComplianceStatus": "Compliant"
    }

  • Response:

    {
      "SPVID": "abc123",
      "Name": "New SPV",
      "Purpose": "Investment",
      "CreationDate": "2024-05-01",
      "Status": "Active",
      "ParentCompanyID": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
      "ComplianceStatus": "Compliant"
    }

3.8. Convertible Notes

• Create Convertible Note:
  • API Endpoint: POST /api/v2/convertible-notes
  • Description: Create a new convertible note.
  • Request Body:

    {
      "issuerId": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
      "stakeholderId": "7af7123a-2ee9-4e31-a173-54b8f9159426",
      "securityLabel": "CN-01",
      "issueDatetime": "2024-06-01T10:00:00Z",
      "maturityDatetime": "2026-06-01T10:00:00Z",
      "interest": 5.0,
      "principal": 1000000,
      "interestRate": 5.0,
      "priceCap": 20000000,
      "discountPercentage": 20.0
    }

  • Response:

    {
      "id": "con123",
      "issuerId": "d68e5604-6107-4f56-baf1-4cc09d7d0c50",
      "stakeholderId": "7af7123a-2ee9-4e31-a173-54b8f9159426",
      "securityLabel": "CN-01",
      "issueDatetime": "2024-06-01T10:00:00Z",
      "maturityDatetime": "2026-06-01T10:00:00Z",
      "interest": 5.0,
      "principal": 1000000,
      "interestRate": 5.0,
      "priceCap": 20000000,
      "discountPercentage": 20.0
    }

---

4. Technical Requirements

1. API Standards:

   • Use RESTful principles for API development.
   • Ensure all APIs follow consistent naming conventions and response structures.
   • Include pagination and filtering options for all list endpoints.
   • Implement validation and comprehensive error handling.

2. Authentication & Authorization:

   • Implement OAuth 2.0 for secure access to APIs.
   • Role-based access control (RBAC) to manage user permissions.
   • All API requests must include an Authorization header with a valid token.

3. Data Model:

   • Use PostgreSQL as the primary database.
   • Follow the detailed data model provided, ensuring relationships and data integrity are enforced.
   • Use UUIDs as primary keys for all tables.

4. Security:

   • Encrypt sensitive data at rest and in transit.
   • Implement regular security audits and compliance checks.
   • Ensure compliance with relevant financial and data protection regulations.

5. Performance:

   • Optimize API response times to ensure sub-second latency for most operations.
   • Use caching strategies where applicable.
   • Design the system to handle high concurrency.

6. Scalability:

   • Ensure the system can scale horizontally to handle increasing workloads.
   • Use containerization (e.g., Docker) and orchestration (e.g., Kubernetes) to manage deployments.

7. Logging & Monitoring:

   • Implement centralized logging for all API requests and responses.
   • Set up monitoring and alerting for API performance, errors, and security events.

---

5. Non-Functional Requirements

1. **Us

ability:**

• Ensure the platform is intuitive and user-friendly.
• Provide comprehensive API documentation with examples.

2. Reliability:

   • Implement redundancy for all critical services.
   • Ensure 99.9% uptime for the API platform.

3. Maintainability:

   • Use a modular architecture to allow for easy updates and maintenance.
   • Document all code and system designs thoroughly.

4. Compliance:

   • Ensure the platform meets financial regulatory requirements (e.g., SOX, GDPR).
   • Regularly update the platform to comply with new regulations.

---

6. Project Timeline

1. Phase 1: API Development

   • Duration: 6 weeks
   • Milestones:
     • Completion of corporation, issuer, compensation, and SPV APIs.
     • Completion of initial security implementation.

2. Phase 2: Frontend & Integration

   • Duration: 4 weeks
   • Milestones:
     • Development of user interfaces for stakeholders.
     • Integration of frontend with backend APIs.
     • User testing and feedback loop.

3. Phase 3: Finalization & Deployment

   • Duration: 2 weeks
   • Milestones:
     • Performance testing and optimizations.
     • Final security audits.
     • Go-live and post-launch support.

---

7. Risks & Mitigations

1. Risk: API performance issues under high load.

   • Mitigation: Implement load testing early in development and optimize queries.

2. Risk: Security vulnerabilities due to sensitive financial data.

   • Mitigation: Conduct regular security audits and use encryption for all sensitive data.

3. Risk: Compliance with evolving regulations.

   • Mitigation: Engage legal experts to ensure compliance and stay updated with regulatory changes.

---

8. Acceptance Criteria

1. APIs:

   • All endpoints must pass functional, integration, and performance tests.
   • APIs should handle at least 10,000 requests per minute with no degradation in performance.

2. User Interface:

   • The UI must be responsive, intuitive, and match the provided designs.
   • No critical UI bugs should be present at the time of launch.

3. Security:

   • All security tests must pass, including penetration testing and vulnerability scans.
   • Role-based access control must be fully implemented and tested.

4. Compliance:

   • The platform must pass all compliance checks before go-live.