Skip to content

development-plan.md

Latest commit

 

History

History
203 lines (154 loc) · 8.71 KB

development-plan.md

File metadata and controls

203 lines (154 loc) · 8.71 KB

Worderner Development Plan

This document outlines the step-by-step plan for building Worderner, including a suggested tech stack, architecture overview, and how AI tools will be integrated into the development workflow.

1. Suggested Tech Stack

These are initial recommendations and can be refined as architecture decisions are made.

  • Frontend

    • Framework: React (with Next.js or similar meta-framework for SSR/SSG).
    • Language: TypeScript.
    • Styling: Tailwind CSS or a modern component library (e.g., MUI/Chakra) plus custom components.

  • Backend (Off-Chain Application Layer)

    • Runtime: Node.js (TypeScript).
    • Framework: Express, NestJS, or a Next.js API layer (to be decided).
    • Persistence: PostgreSQL (via Prisma or similar ORM).

  • On-Chain / Web3 Layer (Pluggable)

    • Target: An EVM-compatible chain or other L1/L2 suitable for low-fee, transparent scholarship logic (testnet first, then mainnet/main L2).
    • Smart contracts for:
      • Scholarship escrow (funds locked in contract, not in institutional accounts).
      • Milestone-based disbursement rules (percentages per milestone, failure handling).
      • Scholarship DAOs (community pools, on-chain voting, treasury logic) in later phases.
    • Web3 integration library (e.g., ethers.js, viem) abstracted behind a backend or shared service.

  • Payments

    • Stablecoin: USDC (or another regulated USD-pegged stablecoin) as the primary on-chain value unit.
    • Off-ramps: integrations with payment providers that support card, bank, and mobile money payouts (subject to compliance and geography).

  • AI Integration

    • Access to LLM APIs (e.g., OpenAI, Anthropic, or others) abstracted behind a service layer.
    • Clear separation between product logic and AI provider code.

  • Infrastructure & Tooling

    • Package management: npm or pnpm.
    • Testing: Jest / Vitest for unit tests, Playwright/Cypress for E2E.
    • CI/CD: GitHub Actions.
    • Hosting: To be decided (e.g., Vercel/Netlify for frontend, Render/Fly.io/other for backend).

All final decisions (including chain choice, custody model, and compliance constraints) should be documented in an architecture file (to be created once decisions are made).

2. Architecture Overview (High-Level)

Conceptual architecture for the MVP:

  • Client (Web App)

    • Manages UI, routing, and interactions for students, donors, and partners.
    • Communicates with the backend via a JSON API (REST or GraphQL).
    • Optionally interacts with wallets/on-chain components via a web3 provider (in later phases).

  • Application Backend (Off-Chain)

    • Handles authentication, authorization, and user/session management.
    • Exposes endpoints for:
      • Student and donor onboarding.
      • Scholarship creation and management.
      • Milestone submission, review, and status changes.
      • Funding ledger and event history.
      • AI operations (e.g., summarizing journeys, assisting with communication or documentation).
    • Encapsulates business logic separately from API controllers.

  • On-Chain Layer (Future-Ready From Day One)

    • Smart contracts that can represent scholarships, milestones, and custodial logic for funds (escrow + disbursement rules).
    • Initially may be used as:
      • A transparent record of milestones and commitments.
      • A testnet playground for validating contract logic.
    • Interacts with the backend via a dedicated service that:
      • Submits relevant transactions.
      • Listens to events and updates off-chain state.

  • Oracles & Integrations

    • Oracle layer (initially simple, later more automated) that:
      • Accepts signed milestone verification data from university partners or trusted reviewers.
      • Posts verification results to smart contracts where required.
    • Longer-term integrations with registrar systems and credential providers.

  • AI Service Layer

    • A dedicated module/service for:
      • Constructing prompts (e.g., summarizing student journeys, generating messages to donors).
      • Calling external LLM APIs.
      • Handling rate limits, retries, and safety checks.
    • Provides stable, typed interfaces to the rest of the backend.

  • Data Layer

    • Data models for:
      • Users (students, donors, employers, admins).
      • Scholarships and milestones.
      • Funding commitments and disbursement events (off-chain ledger).
    • Repositories/ORM models isolated from business logic.

A more detailed architecture diagram and decisions can be captured later in a dedicated document, e.g., docs/development/architecture.md.

3. Step-by-Step Build Plan

Phase 0 – Foundations

  1. Initialize monorepo or app structure (e.g., a Next.js app with TypeScript).
  2. Set up linting, formatting, testing, and CI.
  3. Implement basic health checks and environment configuration.

Phase 1 – Core Data & Workflow Model

  1. Define data models for:
    • User (roles: student, donor, employer, admin).
    • Scholarship (funding amount, milestones, rules).
    • Milestone (type, due date, status, evidence, verification data).
    • FundingEvent / Ledger entry.
  2. Implement persistence with migrations.
  3. Create basic APIs for CRUD operations on scholarships, milestones, and user profiles.

Phase 2 – Basic UI and Milestone Workflow

  1. Create UI for:
    • Student dashboard (view scholarships, milestones, required actions).
    • Donor dashboard (view funded students, scholarships, progress).
    • Creating a new scholarship (simple flow).
  2. Implement client-side state management and routing.
  3. Implement milestone submission and manual verification workflow.

Phase 3 – Funding Ledger and (Simulated) Disbursement

  1. Implement an off-chain ledger model for tracking:
    • Committed vs. released vs. remaining funds.
    • Events when milestones are verified and funds are “released”.
  2. Expose this ledger via APIs and UI timelines for students and donors.
  3. Integrate with testnet/on-chain contracts to mirror these events, validating scholarship and milestone contract designs.

Phase 4 – On-Chain & Payment Integrations (Optional Early, Required Later)

  1. Design and deploy initial smart contracts to represent scholarships and milestones.
  2. Integrate the backend with the on-chain layer for:
    • Writing scholarship and milestone data.
    • Subscribing to events.
  3. Integrate payment rails:
    • USDC on the chosen chain as the core settlement asset.
    • Custodial or semi-custodial flows for students who are not crypto-native.
    • Off-ramps into local payment methods in priority geographies.

Phase 5 – AI-Assisted Features and Experience

  1. Implement AI service layer in the backend.
  2. Add endpoints and flows for:
    • Summarizing a student’s journey for donors and employers.
    • Helping students craft updates or applications based on their history.
  3. Build UI components to:
    • Trigger AI actions.
    • Show AI-generated summaries or messages for review and editing.
  4. Optionally support AI-assisted matching between donors/DAOs and students based on field of study, milestones, geography, and trust score.

4. AI-Assisted Development Workflow

AI tools are integral to how this project is built. The goal is to use AI to accelerate development without sacrificing clarity or quality.

4.1 When to Use AI

  • Generating boilerplate code (e.g., components, API handlers, models).
  • Drafting tests, documentation, and examples.
  • Exploring alternative implementations or refactors.
  • Translating product requirements (from docs/product) into initial code scaffolds.

4.2 How to Prompt AI for Code

  • Always reference:
    • The relevant specification (e.g., a section from product-spec.md).
    • The desired file(s) and location in the codebase.
    • The constraints (tech stack, patterns, style).
  • Prefer small, focused prompts over huge multi-file requests.
  • Ask AI to:
    • Provide code.
    • Explain trade-offs when options are non-trivial.
    • Suggest tests for new logic.

For more detailed prompting patterns and examples, see docs/prompts/ai-development-guide.md.

4.3 Validating AI-Generated Code

  1. Code review
    • No AI-generated changes are merged without human review.
    • Review for readability, correctness, and alignment with product docs.
  2. Testing
    • Add or update unit tests and integration tests.
    • Run the full test suite locally and/or in CI.
  3. Traceability
    • Link pull requests and commits back to:
      • A GitHub Issue.
      • A section in the product/development docs (if relevant).

5. Keeping This Plan Up to Date

  • When architecture or tech stack decisions change, update this document and/or add focused design docs.
  • When new phases or major features are planned, reflect them in docs/roadmap/roadmap.md and link them back here.
  • Treat this file as a living document that evolves with the project.