diff --git a/.env.example b/.env.example index ca96d0f..67dd4ec 100644 --- a/.env.example +++ b/.env.example @@ -1,7 +1,8 @@ # =========================================== -# Oreko Environment Variables +# Oreko Environment Variables (root — used by Docker) # =========================================== -# Copy this file to .env.local and fill in the values +# For Next.js development, use apps/web/.env.example instead: +# cp apps/web/.env.example apps/web/.env.local # Application NODE_ENV=development diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100644 index 0000000..c27d889 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1 @@ +lint-staged diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c07e3f..efd9fdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,7 @@ Oreko is an open-source, self-hosted visual quote and invoice management tool de By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone. Please be respectful, considerate, and constructive in all interactions. Key principles: + - Be welcoming and inclusive - Be respectful of differing viewpoints - Accept constructive criticism gracefully @@ -42,24 +43,30 @@ When creating a bug report, please use the following template: ```markdown ## Bug Description + A clear and concise description of what the bug is. ## Steps to Reproduce + 1. Go to '...' 2. Click on '...' 3. Scroll down to '...' 4. See error ## Expected Behavior + A clear description of what you expected to happen. ## Actual Behavior + What actually happened instead. ## Screenshots + If applicable, add screenshots to help explain the problem. ## Environment + - OS: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11] - Browser: [e.g., Chrome 120, Firefox 121] - Node.js version: [e.g., 20.10.0] @@ -67,6 +74,7 @@ If applicable, add screenshots to help explain the problem. - Oreko version/commit: [e.g., v1.0.0 or commit hash] ## Additional Context + Add any other context about the problem here, including error logs from the console or server. ``` @@ -82,24 +90,31 @@ Have an idea for a new feature? We'd love to hear it! Before suggesting a featur ```markdown ## Feature Summary + A brief, one-line description of the feature. ## Problem Statement + What problem does this feature solve? Who would benefit from it? ## Proposed Solution + Describe your proposed solution in detail. ## Alternative Solutions + Have you considered any alternative approaches? What are their pros and cons? ## Additional Context + - Mock-ups or wireframes (if applicable) - Examples from other applications - Any technical considerations ## Priority Suggestion + Where do you think this fits? + - [ ] P0 - Critical for MVP - [ ] P1 - Should have for v1.1 - [ ] P2 - Nice to have for future versions @@ -113,9 +128,8 @@ Before you begin, ensure you have the following installed: - Node.js 20+ - pnpm 8+ -- Docker and Docker Compose +- Docker and Docker Compose (recommended for PostgreSQL and Mailpit) - PostgreSQL 15+ (or use Docker) -- Redis 7+ (or use Docker) - Git ### Getting Started @@ -141,13 +155,12 @@ pnpm install #### 3. Set Up Environment ```bash -# Copy the example environment file +# Copy the environment file for the web app cp apps/web/.env.example apps/web/.env.local -# Edit .env.local with your local configuration +# Edit apps/web/.env.local with your local configuration # Required variables: # - DATABASE_URL -# - REDIS_URL # - NEXTAUTH_SECRET # - NEXTAUTH_URL ``` @@ -172,14 +185,14 @@ pnpm dev Use descriptive branch names with the appropriate prefix: -| Prefix | Use Case | Example | -|--------|----------|---------| -| `feature/` | New features | `feature/quote-pdf-export` | -| `fix/` | Bug fixes | `fix/invoice-calculation-error` | -| `chore/` | Maintenance tasks | `chore/update-dependencies` | -| `docs/` | Documentation only | `docs/api-reference` | -| `refactor/` | Code refactoring | `refactor/quote-builder-hooks` | -| `test/` | Test additions/fixes | `test/stripe-integration` | +| Prefix | Use Case | Example | +| ----------- | -------------------- | ------------------------------- | +| `feature/` | New features | `feature/quote-pdf-export` | +| `fix/` | Bug fixes | `fix/invoice-calculation-error` | +| `chore/` | Maintenance tasks | `chore/update-dependencies` | +| `docs/` | Documentation only | `docs/api-reference` | +| `refactor/` | Code refactoring | `refactor/quote-builder-hooks` | +| `test/` | Test additions/fixes | `test/stripe-integration` | ### Creating a Branch @@ -208,19 +221,19 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear #### Types -| Type | Description | -|------|-------------| -| `feat` | A new feature | -| `fix` | A bug fix | -| `docs` | Documentation changes only | -| `style` | Code style changes (formatting, semicolons, etc.) | +| Type | Description | +| ---------- | --------------------------------------------------- | +| `feat` | A new feature | +| `fix` | A bug fix | +| `docs` | Documentation changes only | +| `style` | Code style changes (formatting, semicolons, etc.) | | `refactor` | Code changes that neither fix bugs nor add features | -| `perf` | Performance improvements | -| `test` | Adding or updating tests | -| `build` | Build system or dependency changes | -| `ci` | CI/CD configuration changes | -| `chore` | Other changes that don't modify src or test files | -| `revert` | Reverts a previous commit | +| `perf` | Performance improvements | +| `test` | Adding or updating tests | +| `build` | Build system or dependency changes | +| `ci` | CI/CD configuration changes | +| `chore` | Other changes that don't modify src or test files | +| `revert` | Reverts a previous commit | #### Scopes (optional) @@ -286,13 +299,13 @@ git rebase upstream/main ### Naming Conventions -| Element | Convention | Example | -|---------|------------|---------| -| Components | PascalCase | `QuoteBuilder.tsx` | -| Utilities | camelCase | `formatCurrency.ts` | -| Constants | UPPER_SNAKE_CASE | `API_ENDPOINTS` | -| CSS classes | Tailwind utility-first | `className="flex items-center"` | -| Database tables | snake_case | `quote_line_items` | +| Element | Convention | Example | +| --------------- | ---------------------- | ------------------------------- | +| Components | PascalCase | `QuoteBuilder.tsx` | +| Utilities | camelCase | `formatCurrency.ts` | +| Constants | UPPER_SNAKE_CASE | `API_ENDPOINTS` | +| CSS classes | Tailwind utility-first | `className="flex items-center"` | +| Database tables | snake_case | `quote_line_items` | ### File Organization @@ -360,11 +373,11 @@ All contributions must include appropriate tests. Our testing strategy: ### Test Types -| Type | Tool | Location | Purpose | -|------|------|----------|---------| -| Unit | Vitest | `*.test.ts` | Utilities, hooks, pure functions | -| Component | React Testing Library | `*.test.tsx` | Component behavior | -| E2E | Playwright | `e2e/*.spec.ts` | Critical user flows | +| Type | Tool | Location | Purpose | +| --------- | --------------------- | --------------- | -------------------------------- | +| Unit | Vitest | `*.test.ts` | Utilities, hooks, pure functions | +| Component | React Testing Library | `*.test.tsx` | Component behavior | +| E2E | Playwright | `e2e/*.spec.ts` | Critical user flows | ### Running Tests @@ -444,9 +457,11 @@ describe('calculateQuoteTotal', () => { ```markdown ## Description + Brief description of changes and motivation. ## Type of Change + - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) @@ -454,9 +469,11 @@ Brief description of changes and motivation. - [ ] Refactoring (no functional changes) ## Related Issues + Fixes #(issue number) ## How Has This Been Tested? + Describe the tests you ran to verify your changes. - [ ] Unit tests @@ -465,9 +482,11 @@ Describe the tests you ran to verify your changes. - [ ] Manual testing ## Screenshots (if applicable) + Add screenshots for UI changes. ## Checklist + - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code where necessary @@ -583,4 +602,3 @@ pnpm db:studio # Open Prisma Studio --- Thank you for contributing to Oreko! Your efforts help make quote and invoice management better for small businesses everywhere. - diff --git a/README.md b/README.md index ba57ef9..37c19a1 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) +[![CI](https://github.com/orekoapp/oreko/actions/workflows/ci.yml/badge.svg)](https://github.com/orekoapp/oreko/actions/workflows/ci.yml) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/) [![Next.js](https://img.shields.io/badge/Next.js-14+-black.svg)](https://nextjs.org/) @@ -39,10 +40,10 @@ ## What You Can Do With Oreko -+ [Visual Quote Builder](#visual-quote-builder) -+ [Invoicing with one-click conversion](#invoicing-with-one-click-conversion) -+ [Client Management](#client-management) -+ [Contracts, payments, and analytics](#contracts-payments-and-analytics) +- [Visual Quote Builder](#visual-quote-builder) +- [Invoicing with one-click conversion](#invoicing-with-one-click-conversion) +- [Client Management](#client-management) +- [Contracts, payments, and analytics](#contracts-payments-and-analytics) ### Visual Quote Builder @@ -70,42 +71,47 @@ Centralized client database with full history, lifetime value tracking, and cont ### Contracts, payments, and analytics -| Feature | Description | -| ------------------------------ | -------------------------------------------------------------------------- | -| **E-Signature Capture** | Legally compliant electronic signatures (E-SIGN, UETA) | -| **Stripe Payment Integration** | Accept credit cards and ACH payments via Stripe Connect | -| **PDF Generation** | Professional PDF exports for quotes and invoices | -| **Email Notifications** | Automated email workflows for quotes, invoices, and reminders | +| Feature | Description | +| ------------------------------ | --------------------------------------------------------------------------- | +| **E-Signature Capture** | Legally compliant electronic signatures (E-SIGN, UETA) | +| **Stripe Payment Integration** | Accept credit cards and ACH payments via Stripe Connect | +| **PDF Generation** | Professional PDF exports for quotes and invoices | +| **Email Notifications** | Automated email workflows for quotes, invoices, and reminders | | **Dashboard Analytics** | Revenue trends, quote conversion rates, invoice status, and client insights | -| **Contract Templates** | Draft contracts from templates, send for e-signature | -| **Rate Card System** | Predefined services and pricing tiers for quick quoting | -| **Milestone Payments** | Support for deposits, milestones, and recurring payments | -| **Modular Workspace** | Enable only the modules you need | -| **Self-Hosted** | Full control over your data with Docker deployment | +| **Contract Templates** | Draft contracts from templates, send for e-signature | +| **Rate Card System** | Predefined services and pricing tiers for quick quoting | +| **Milestone Payments** | Support for deposits, milestones, and recurring payments | +| **Modular Workspace** | Enable only the modules you need | +| **Self-Hosted** | Full control over your data with Docker deployment |
## Quick Start -### Docker (Recommended) +### Using Docker for Services + +The base `docker-compose.yml` runs supporting services (PostgreSQL, Mailpit) while you run Next.js locally: ```bash git clone https://github.com/orekoapp/oreko.git cd oreko -cp .env.example .env -docker-compose up -d -docker-compose exec web pnpm db:migrate +cp apps/web/.env.example apps/web/.env.local # Next.js loads .env.local from apps/web/ +docker-compose up -d # Start Postgres and Mailpit +pnpm install +pnpm db:migrate +pnpm dev ``` Open `http://localhost:3000` -### Manual Installation +### Manual Installation (No Docker) ```bash git clone https://github.com/orekoapp/oreko.git cd oreko pnpm install -cp .env.example .env +cp apps/web/.env.example apps/web/.env.local # Next.js loads .env.local from apps/web/ +# Ensure PostgreSQL is running and DATABASE_URL is set in apps/web/.env.local pnpm db:migrate pnpm dev ``` @@ -119,7 +125,6 @@ See the [full setup guide](https://oreko.app/docs) for detailed instructions. - [TypeScript](https://www.typescriptlang.org/) 5.x - [Next.js](https://nextjs.org/) 14+ (App Router) - [Prisma](https://www.prisma.io/) + [PostgreSQL](https://www.postgresql.org/) -- [Redis](https://redis.io/) + [BullMQ](https://bullmq.io/) - [Shadcn UI](https://ui.shadcn.com/) + [Tailwind CSS](https://tailwindcss.com/) - [Stripe Connect](https://stripe.com/connect) for payments - [Turborepo](https://turbo.build/) monorepo @@ -131,6 +136,8 @@ See the [full setup guide](https://oreko.app/docs) for detailed instructions. We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details. +Check `specs/PRODUCT_SPEC.md` for the roadmap and `specs/TECHNICAL_SPEC.md` for architecture details. + ```bash # Fork, clone, then: pnpm install diff --git a/apps/web/.env.example b/apps/web/.env.example index 53c5127..618bdc1 100644 --- a/apps/web/.env.example +++ b/apps/web/.env.example @@ -11,9 +11,6 @@ NEXT_PUBLIC_APP_NAME=Oreko # Database (PostgreSQL) DATABASE_URL="postgresql://oreko:oreko@localhost:5432/oreko?schema=public" -# Redis (required for BullMQ job queue) -REDIS_URL=redis://localhost:6379 - # Authentication (NextAuth.js) NEXTAUTH_URL=http://localhost:3000 NEXTAUTH_SECRET= # Generate with: openssl rand -base64 32 diff --git a/docker-compose.yml b/docker-compose.yml index 234b4b8..64c07e2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -28,11 +28,11 @@ services: container_name: oreko-mailpit restart: unless-stopped ports: - - '8025:8025' # Web UI - - '1025:1025' # SMTP + - '127.0.0.1:8025:8025' # Web UI + - '127.0.0.1:1025:1025' # SMTP environment: - MP_SMTP_AUTH_ACCEPT_ANY: 1 # Dev-only: accept any SMTP credentials - MP_SMTP_AUTH_ALLOW_INSECURE: 1 # Dev-only: allow plaintext auth + MP_SMTP_AUTH_ACCEPT_ANY: 1 # Dev-only: accept any SMTP credentials + MP_SMTP_AUTH_ALLOW_INSECURE: 1 # Dev-only: allow plaintext auth volumes: postgres_data: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d41d647 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,60 @@ +# Oreko Documentation + +A guide to the documentation in this directory. + +## Getting Started + +| Document | Description | +| ------------------------------- | --------------------------------------- | +| [Developer Guide](DEVELOPER.md) | Local development setup and workflows | +| [Docker Guide](DOCKER.md) | Docker-based development and deployment | +| [User Guide](USER_GUIDE.md) | End-user documentation | + +## Architecture & Design + +| Document | Description | +| ------------------------------------------------------- | ----------------------------- | +| [Architecture](ARCHITECTURE.md) | System architecture overview | +| [Design Patterns](DESIGN_PATTERNS.md) | Code patterns and conventions | +| [Component Design](COMPONENT_DESIGN.md) | UI component architecture | +| [E-Signature Architecture](E_SIGNATURE_ARCHITECTURE.md) | E-signature system design | +| [Phase 2 Architecture](PHASE2_ARCHITECTURE.md) | Phase 2 architectural plans | +| [Phase 2 UI Design](PHASE2_UI_DESIGN.md) | Phase 2 UI design plans | + +## API Reference + +| Document | Description | +| --------------------------------- | -------------------------- | +| [API Overview](API.md) | API design and endpoints | +| [API Reference](API_REFERENCE.md) | Detailed API documentation | + +## User Flows + +| Document | Description | +| --------------------------- | -------------------------- | +| [User Flows](USER_FLOWS.md) | User journey documentation | + +## Testing + +| Document | Description | +| ----------------------------------------- | ------------------------- | +| [Manual Test Cases](MANUAL_TEST_CASES.md) | Manual testing procedures | + +## Internal Planning + +> **Note:** These documents are internal team planning artifacts. They are not required reading for contributors but are kept here for transparency. + +| Document | Description | +| ------------------------------------------------------------------- | ------------------------------ | +| [Architecture Analysis](ARCHITECTURE_ANALYSIS.md) | Architecture review notes | +| [Technical Analysis](TECHNICAL_ANALYSIS.md) | Technical assessment | +| [Clarifications](CLARIFICATIONS.md) | Design decision clarifications | +| [New Design Analysis](NEW_DESIGN_ANALYSIS.md) | Design refresh analysis | +| [New Design Implementation Plan](NEW_DESIGN_IMPLEMENTATION_PLAN.md) | Design refresh implementation | +| [Implementation Spec](IMPLEMENTATION_SPEC.md) | Feature implementation details | +| [Implementation Plan](IMPLEMENTATION_PLAN.md) | Development execution plan | +| [Implementation Gap Plan](IMPLEMENTATION_GAP_PLAN.md) | Gap analysis and remediation | +| [Execution Plan](EXECUTION_PLAN_CRITICAL_HIGH.md) | Priority execution tracking | +| [E2E Feature Gaps Plan](E2E_FEATURE_GAPS_PLAN.md) | E2E test coverage gaps | +| [Test Coverage Analysis](TEST_COVERAGE_ANALYSIS.md) | Test coverage assessment | +| [Estimation](ESTIMATION.md) | Effort estimation |