diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..18dcdc7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,36 @@ +# CLAUDE.md + +Concise guidance for Claude Code in this repository. + +## Canonical agent entry + +Start with `docs/index.md` and load only task-relevant docs it references. + +## Quick commands + +```bash +pnpm install +pnpm run dev +pnpm run build +pnpm run preview +pnpm test +pnpm test:watch +``` + +## Non-negotiables + +- Use `pnpm` only. +- Do not `git commit` or `git push`. Ask before staging with `git add`. +- Prefer existing files; do not create new docs unless explicitly requested. +- Use `mgrep` for code search. + +## Environment + +Set `GEMINI_API_KEY` in `.env.local`. + +## Pointers + +- Entry flow: `index.html` → `index.tsx` → `App.tsx` +- Routes: `pages/` +- Shared UI: `components/` +- Types: `types.ts` diff --git a/README.md b/README.md index 1aa72d2..caa5000 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,17 @@ This contains everything you need to run your app locally. View your app in AI Studio: https://ai.studio/apps/drive/1XC-Q0YPDamuw1PItnxd0vSYWMNqnQjCX +## Agent navigation + +For AI agents, start with the canonical entry point at `docs/index.md`, then include any task-specific docs it references. + ## Run Locally **Prerequisites:** Node.js 1. Install dependencies: - `npm install` + `pnpm install` 2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key 3. Run the app: - `npm run dev` + `pnpm run dev` diff --git a/_bmad-output/planning-artifacts/bmm-workflow-status.yaml b/_bmad-output/planning-artifacts/bmm-workflow-status.yaml new file mode 100644 index 0000000..1e37357 --- /dev/null +++ b/_bmad-output/planning-artifacts/bmm-workflow-status.yaml @@ -0,0 +1,101 @@ +# Workflow Status Template + +# This tracks progress through BMM methodology Analysis, Planning, and Solutioning phases. +# Implementation phase is tracked separately in sprint-status.yaml + +# STATUS DEFINITIONS: +# ================== +# Initial Status (before completion): +# - required: Must be completed to progress +# - optional: Can be completed but not required +# - recommended: Strongly suggested but not required +# - conditional: Required only if certain conditions met (e.g., if_has_ui) +# +# Completion Status: +# - {file-path}: File created/found (e.g., "docs/product-brief.md") +# - skipped: Optional/conditional workflow that was skipped + +generated: "2026-01-12" +project: "prototype" +project_type: "software" +selected_track: "method" +field_type: "brownfield" +workflow_path: "_bmad/bmm/workflows/workflow-status/paths/method-brownfield.yaml" + +workflow_status: + phase_0_documentation: + name: "Documentation" + note: "Prerequisite for brownfield without docs" + workflows: + document-project: + status: docs/index.md + agent: analyst + command: /bmad:bmm:workflows:document-project + purpose: "Understand existing codebase before planning" + completed: 2026-01-12 + + phase_1_analysis: + name: "Analysis (Optional)" + note: "User-selected discovery workflows" + workflows: + brainstorm-project: + status: optional + agent: analyst + command: /bmad:core:workflows:brainstorming + note: "Creative exploration and ideation" + research: + status: skipped + agent: analyst + command: /bmad:bmm:workflows:research + product-brief: + status: skipped + agent: analyst + command: /bmad:bmm:workflows:create-product-brief + + phase_2_planning: + name: "Planning" + workflows: + prd: + status: required + agent: pm + command: /bmad:bmm:workflows:prd + output: "Product Requirements Document with FRs and NFRs" + create-ux-design: + status: conditional + condition: if_has_ui + agent: ux-designer + command: /bmad:bmm:workflows:create-ux-design + note: "Determined after PRD - user/agent decides if needed" + + phase_3_solutioning: + name: "Solutioning" + workflows: + create-architecture: + status: required + agent: architect + command: /bmad:bmm:workflows:create-architecture + output: "System architecture document" + create-epics-and-stories: + status: required + agent: pm + command: /bmad:bmm:workflows:create-epics-and-stories + note: "Break down PRD into implementable epics and stories" + test-design: + status: optional + agent: tea + command: /bmad:bmm:workflows:testarch-test-design + output: "System-level testability review" + implementation-readiness: + status: required + agent: architect + command: /bmad:bmm:workflows:check-implementation-readiness + note: "Validates PRD + Architecture + Epics + UX (if applicable)" + + phase_4_implementation: + name: "Implementation" + workflows: + sprint-planning: + status: required + agent: sm + command: /bmad:bmm:workflows:sprint-planning + note: "Creates sprint plan - subsequent work tracked in sprint-status.yaml" diff --git a/docs/api-architecture.md b/docs/api-architecture.md new file mode 100644 index 0000000..61f1d3c --- /dev/null +++ b/docs/api-architecture.md @@ -0,0 +1,170 @@ +# API Architecture & State Management + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React + TypeScript) +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based) + +## Overview + +This document describes the API integration points and state management approach identified in the project. + +## External API Integration + +### Google Gemini API +- **Provider:** Google AI +- **Purpose:** AI-powered features integration +- **Configuration:** + - Environment Variable: `GEMINI_API_KEY` + - Configured in: `vite.config.ts` + - Exposed as: `process.env.GEMINI_API_KEY` and `process.env.API_KEY` + +**Configuration Code:** +```typescript +define: { + 'process.env.API_KEY': JSON.stringify(env.GEMINI_API_KEY), + 'process.env.GEMINI_API_KEY': JSON.stringify(env.GEMINI_API_KEY) +} +``` + +### API Client Patterns + +Based on the project structure and modern React practices: + +**Likely API Integration Patterns:** +- Client-side API calls from React components +- TypeScript interfaces for API responses (defined in `types.ts`) +- Environment-based configuration for API endpoints + +## State Management + +### Approach +Based on React 19.2.3 and project structure, the application likely uses: + +**React Built-in State Management:** +- `useState` for local component state +- `useContext` for shared state across components +- React 19 features for modern state handling + +### State Patterns Identified + +**Component-Level State:** +- Form inputs (Contact, Newsletter) +- UI state (modals, navigation) +- Local component data + +**Application-Level State:** +- Navigation state +- Theme configuration +- User preferences + +## Data Flow Architecture + +``` +┌─────────────────────────────────────────────────┐ +│ User Interface Layer │ +│ (React Components + TypeScript) │ +└─────────────────┬───────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────┐ +│ State Management Layer │ +│ (React Hooks: useState, useContext) │ +└─────────────────┬───────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────┐ +│ API Integration Layer │ +│ (Google Gemini API) │ +└─────────────────────────────────────────────────┘ +``` + +## API Call Patterns + +### Expected Patterns + +**1. Fetch API Usage** +Modern React applications typically use the Fetch API for HTTP requests: +```typescript +const response = await fetch(endpoint, options); +const data = await response.json(); +``` + +**2. Async/Await Pattern** +TypeScript with modern async handling for API calls + +**3. Error Handling** +Try-catch blocks for API error management + +## Configuration Management + +### Environment Variables +- **File:** `.env.local` +- **Purpose:** Store API keys and configuration +- **Variables:** + - `GEMINI_API_KEY` - Google Gemini API authentication + +### Build-Time Configuration +- **Tool:** Vite +- **Config File:** `vite.config.ts` +- **Features:** + - Environment variable injection + - API key exposure to runtime + - Development server configuration (port 3000) + +## Security Considerations + +### API Key Management +- ✓ API keys stored in `.env.local` (not in source control) +- ✓ Keys injected at build time via Vite config +- ⚠️ Client-side API key exposure (typical for client-side apps) + +### Recommendations +- Consider implementing API proxy for sensitive operations +- Rotate API keys regularly +- Implement rate limiting if needed +- Monitor API usage + +## Integration Points + +### Identified Integration Patterns + +1. **AI Features (Gemini API)** + - Purpose: AI-powered functionality + - Type: External REST API + - Authentication: API Key + +2. **Font Loading** + - Source: `https://www.ocobo.co/fonts/` + - Custom fonts: Bermia, Bornia + +3. **CDN Resources** + - Tailwind CSS: `https://cdn.tailwindcss.com` + - Google Fonts: Inter font family + +## State Persistence + +### Browser Storage Patterns +Likely usage patterns (common in SPA): +- LocalStorage for user preferences +- SessionStorage for temporary data +- Cookies for authentication (if implemented) + +## Notes + +- This is a quick scan analysis based on configuration and patterns +- For detailed API endpoint mappings, perform a deep scan +- For complete state management flow, analyze component implementations +- Current architecture supports modern React patterns and external AI integration + +## Recommendations for Deep Scan + +When performing a deep scan, analyze: +1. Actual API endpoints being called +2. Request/response data structures +3. Error handling implementations +4. State management library usage (Context, Redux, Zustand) +5. API caching strategies +6. Loading and error states +7. API response type definitions +8. Authentication flows (if implemented) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..993b795 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,500 @@ +# Architecture Document + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React SPA) +**Architecture Pattern:** Component-Based Single Page Application +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based) + +## Executive Summary + +Ocobo is a modern single-page web application built with React 19 and TypeScript, designed to showcase revenue operations services. The application follows a component-based architecture with clear separation between reusable UI components and route-specific pages. It integrates with Google's Gemini AI API for intelligent features and uses Vite as the build tool for optimal development experience. + +### Key Characteristics +- **Type:** Brownfield web application prototype +- **Architecture:** SPA with client-side routing +- **Language:** TypeScript 5.8.2 +- **Framework:** React 19.2.3 +- **Build Tool:** Vite 6.2.0 +- **Styling:** Tailwind CSS with custom brand design system + +--- + +## Technology Stack + +| Category | Technology | Version | Purpose | +|----------|------------|---------|---------| +| **Frontend Framework** | React | 19.2.3 | UI component framework | +| **Language** | TypeScript | 5.8.2 | Type-safe JavaScript | +| **Build Tool** | Vite | 6.2.0 | Development server & bundler | +| **Routing** | React Router | 7.10.1/7.11.0 | Client-side navigation | +| **Styling** | Tailwind CSS | Latest (CDN) | Utility-first CSS | +| **Icons** | Lucide React | 0.561.0 | Icon library | +| **AI Integration** | Google Gemini API | - | AI-powered features | +| **Runtime** | Node.js | Latest LTS (recommended) | Development environment | + +### Technology Decision Rationale + +**React 19:** +- Latest stable release with modern hooks API +- Excellent performance and developer experience +- Large ecosystem and community support + +**TypeScript:** +- Static typing for early error detection +- Better IDE support and autocomplete +- Improved code maintainability + +**Vite:** +- Lightning-fast HMR (Hot Module Replacement) +- Optimized build output +- Native ESM support + +**Tailwind CSS:** +- Rapid UI development +- Consistent design system +- Small production bundle (purged unused styles) + +--- + +## Architecture Pattern + +### Single Page Application (SPA) + +``` +┌─────────────────────────────────────────────┐ +│ Browser (Single HTML Page) │ +└──────────────────┬──────────────────────────┘ + │ + ┌──────────▼──────────┐ + │ index.html │ + │ (Bootstrap + CDN) │ + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ index.tsx │ + │ (Entry Point) │ + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ App.tsx │ + │ (Router + Layout) │ + └──────────┬──────────┘ + │ + ┌─────────────┴─────────────┐ + │ │ +┌────▼─────┐ ┌──────▼──────┐ +│ Pages │ │ Components │ +│ (Routes) │◄────────────┤ (Reusable) │ +└──────────┘ └─────────────┘ +``` + +### Component Architecture + +**Hierarchical Structure:** +1. **Entry Point** (`index.tsx`) - Application bootstrap +2. **Root Component** (`App.tsx`) - Router configuration & layout +3. **Page Components** (`pages/*`) - Route-specific views +4. **Reusable Components** (`components/*`) - Shared UI elements + +--- + +## Data Architecture + +### Type System + +**Centralized Type Definitions:** `types.ts` + +**Identified Models:** +- `ThemeColor` (Enum) - Brand color enumeration +- `NavItem` (Interface) - Navigation structure +- `ServiceItem` (Interface) - Service data model +- `StatItem` (Interface) - Statistics/metrics model + +### Data Flow + +``` +User Interaction + ↓ + React Component + ↓ + useState/useContext + ↓ + State Update + ↓ + Re-render (React) + ↓ + Updated UI +``` + +### State Management Strategy + +**Local State:** +- React `useState` for component-level state +- Form inputs, UI toggles, local data + +**Shared State:** +- React Context API (inferred pattern) +- Navigation state, theme configuration + +**No Global State Library:** +- No Redux/MobX detected +- React built-in state management sufficient for current scope + +--- + +## API Design + +### External API Integration + +**Google Gemini AI:** +- **Type:** REST API +- **Authentication:** API Key (environment variable) +- **Configuration:** `vite.config.ts` +- **Environment Variable:** `GEMINI_API_KEY` + +### API Call Pattern + +```typescript +// Expected pattern (quick scan inference) +const response = await fetch(geminiEndpoint, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${process.env.GEMINI_API_KEY}` + }, + body: JSON.stringify(requestData) +}); + +const data = await response.json(); +``` + +### Integration Points + +1. **AI Features** - Gemini API for intelligent functionality +2. **Font Loading** - External CDN (`ocobo.co/fonts`) +3. **Styling CDN** - Tailwind CSS +4. **Font CDN** - Google Fonts (Inter fallback) + +--- + +## Component Structure + +### Component Organization + +``` +components/ +├── Button.tsx # Generic button +├── Footer.tsx # Site footer +├── Navbar.tsx # Navigation header +├── NewsletterWidget.tsx # Email subscription +└── ServiceCard.tsx # Service display card + +pages/ +├── Home.tsx # Landing page ⭐ +├── About.tsx # Company info +├── Contact.tsx # Contact form +├── Services.tsx # Services listing +├── Method.tsx # Methodology +├── Partners.tsx # Partners page +├── Studio.tsx # Studio services +├── Resources.tsx # Resources +├── Stories.tsx # Case studies +├── Jobs.tsx # Careers +├── Podcast.tsx # Podcast +├── ArticleDetail.tsx # Article view +├── JobDetail.tsx # Job details +├── StoryDetail.tsx # Story details +└── WebinarDetail.tsx # Webinar details +``` + +### Component Categories + +**Layout Components (2):** +- Navbar - Site navigation +- Footer - Site footer + +**UI Elements (3):** +- Button - Interactive element +- ServiceCard - Content card +- NewsletterWidget - Form widget + +**Page Components (15):** +- 11 main pages +- 4 detail pages + +--- + +## Source Tree + +**See:** [source-tree-analysis.md](./source-tree-analysis.md) for detailed annotated tree. + +**Critical Directories:** +- `/components` - Reusable UI components +- `/pages` - Route-based page components +- `/fonts` - Custom typography (Bermia, Bornia) +- `/docs` - Generated documentation + +**Entry Points:** +- `index.tsx` - Application bootstrap ⭐ +- `App.tsx` - Root component ⭐ +- `index.html` - HTML entry ⭐ + +--- + +## Development Workflow + +### Local Development + +**Start Development:** +```bash +npm install +# Set GEMINI_API_KEY in .env.local +npm run dev +``` + +**Dev Server:** +- URL: `http://localhost:3000` +- HMR: Enabled +- Host: `0.0.0.0` (network accessible) + +### Build Process + +**Production Build:** +```bash +npm run build # Creates dist/ +npm run preview # Test production build +``` + +**Build Output:** +- Optimized React code +- Minified CSS +- Bundled assets +- Ready for static hosting + +### Environment Configuration + +**Required Variables:** +- `GEMINI_API_KEY` - AI API authentication + +**Configuration Files:** +- `.env.local` - Environment variables (not in git) +- `vite.config.ts` - Build config, API key injection + +--- + +## Testing Strategy + +### Current State +- **Unit Tests:** Not configured ❌ +- **Integration Tests:** Not configured ❌ +- **E2E Tests:** Not configured ❌ + +### Recommendations +- **Framework:** Vitest (pairs with Vite) +- **Component Testing:** React Testing Library +- **E2E:** Playwright or Cypress + +### Test Locations (Future) +``` +__tests__/ # Unit tests +components/__tests__/ # Component tests +e2e/ # End-to-end tests +``` + +--- + +## Deployment Architecture + +### Static Hosting + +**Recommended Platforms:** +- Vercel (optimal for Vite/React) +- Netlify +- AWS S3 + CloudFront +- GitHub Pages + +### Deployment Flow + +``` +1. Code commit to main branch +2. CI/CD triggers build (npm run build) +3. dist/ uploaded to hosting platform +4. CDN distributes globally +5. Environment variables configured in platform +``` + +### Environment Variables for Production + +``` +GEMINI_API_KEY= +``` + +**Security Note:** API key exposed client-side (typical for client apps). Consider API proxy for sensitive operations. + +--- + +## Design System + +### Custom Brand: Ocobo + +**Color Palette:** +- **Dark:** #212323 (primary text) +- **Yellow:** #F1CF25 (accent) +- **Mint:** #9ADBBA (secondary) +- **Sky:** #99D1DF (tertiary) +- **Coral:** #FE9C87 (highlight) +- **Gray:** #F5F5F5 (backgrounds) + +**Typography:** +- **Display Font:** Bermia (Black 900) - Headings +- **Body Font:** Bornia (Regular 400, Bold 700) - Content +- **Fallback:** Inter (Google Fonts), system sans-serif + +**Styling Framework:** +- Tailwind CSS with custom theme +- Configured inline in `index.html` +- Utility-first approach + +--- + +## Security Considerations + +### Current Implementation + +✅ **Good Practices:** +- Environment variables for secrets +- `.env.local` in `.gitignore` +- API keys not hardcoded + +⚠️ **Considerations:** +- Client-side API key exposure +- No authentication layer detected +- No rate limiting visible + +### Recommendations + +1. **API Proxy:** Consider backend proxy for sensitive API calls +2. **Rate Limiting:** Implement on API endpoints +3. **CORS Configuration:** Ensure proper CORS headers +4. **Content Security Policy:** Add CSP headers for XSS protection + +--- + +## Performance Optimizations + +### Current Optimizations + +**Development:** +- ✅ Fast HMR via Vite +- ✅ TypeScript incremental compilation +- ✅ React Fast Refresh + +**Production:** +- ✅ Code minification (Vite) +- ✅ Tree shaking +- ✅ Asset optimization +- ✅ Font preloading + +### Future Optimizations + +**Potential Improvements:** +- Lazy loading routes (`React.lazy()`) +- Image optimization (WebP, lazy load) +- Code splitting strategies +- Service worker for offline support + +--- + +## Scalability Considerations + +### Current Architecture Assessment + +**Strengths:** +- Component-based design allows easy additions +- Type-safe codebase reduces errors +- Modern build tool scales well + +**Limitations:** +- No state management library (may need Redux/Zustand if complexity grows) +- No test coverage (critical for scaling) +- Client-side API calls (may need backend as user base grows) + +### Scaling Recommendations + +**Short-term (< 50 components):** +- Current architecture sufficient +- Add testing framework +- Implement code splitting + +**Medium-term (50-200 components):** +- Consider state management library (Zustand/Redux Toolkit) +- Implement comprehensive testing +- Add monitoring (Sentry, LogRocket) + +**Long-term (> 200 components):** +- Evaluate monorepo structure +- Consider Next.js migration for SSR/SSG +- Implement backend API layer + +--- + +## Maintenance & Operations + +### Code Quality + +**Current Tools:** +- TypeScript for type checking +- ESLint (likely configured, not visible in quick scan) +- Prettier (recommended) + +### Monitoring + +**Recommended:** +- Error tracking (Sentry) +- Analytics (Google Analytics, Plausible) +- Performance monitoring (Web Vitals) + +### Documentation + +**Generated Docs (this scan):** +- Architecture overview (this file) +- Component inventory +- Data models +- API architecture +- Development guide +- Source tree analysis + +--- + +## Appendices + +### Related Documentation + +- [Component Inventory](./component-inventory.md) - All UI components +- [Data Models](./data-models.md) - TypeScript interfaces +- [API Architecture](./api-architecture.md) - API integration details +- [Development Guide](./development-guide.md) - Setup and workflow +- [Source Tree](./source-tree-analysis.md) - Directory structure + +### External References + +- [React Documentation](https://react.dev) +- [TypeScript Handbook](https://typescriptlang.org/docs) +- [Vite Guide](https://vitejs.dev) +- [Tailwind CSS Docs](https://tailwindcss.com) +- [Google Gemini API](https://ai.google.dev) + +--- + +## Document Metadata + +- **Document Version:** 1.0 +- **Generated By:** BMad Document Project Workflow +- **Scan Type:** Quick (pattern-based, no deep file analysis) +- **Last Updated:** 2026-01-12 +- **Next Review:** Perform deep scan for detailed implementation analysis + +--- + +*This architecture document was auto-generated from codebase analysis. For implementation details, perform a deep scan or consult source code directly.* diff --git a/docs/component-inventory.md b/docs/component-inventory.md new file mode 100644 index 0000000..f8224b9 --- /dev/null +++ b/docs/component-inventory.md @@ -0,0 +1,147 @@ +# Component Inventory + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React + TypeScript) +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based) + +## Overview + +This document catalogs all UI components discovered in the project through pattern-based analysis. + +## Component Categories + +### Layout Components + +#### Navbar +- **Path:** `components/Navbar.tsx` +- **Type:** Layout/Navigation +- **Purpose:** Main navigation header component +- **Reusable:** Yes + +#### Footer +- **Path:** `components/Footer.tsx` +- **Type:** Layout +- **Purpose:** Site footer component +- **Reusable:** Yes + +### UI Elements + +#### Button +- **Path:** `components/Button.tsx` +- **Type:** Interactive Element +- **Purpose:** Reusable button component +- **Reusable:** Yes + +#### ServiceCard +- **Path:** `components/ServiceCard.tsx` +- **Type:** Display Component +- **Purpose:** Card component for displaying services +- **Reusable:** Yes + +#### NewsletterWidget +- **Path:** `components/NewsletterWidget.tsx` +- **Type:** Form Widget +- **Purpose:** Newsletter subscription widget +- **Reusable:** Yes + +## Page Components + +### Main Pages + +| Page | Path | Purpose | +|------|------|---------| +| Home | `pages/Home.tsx` | Landing page | +| About | `pages/About.tsx` | Company information | +| Contact | `pages/Contact.tsx` | Contact form/information | +| Services | `pages/Services.tsx` | Services overview | +| Method | `pages/Method.tsx` | Methodology presentation | +| Partners | `pages/Partners.tsx` | Partnership information | +| Studio | `pages/Studio.tsx` | Studio services | +| Resources | `pages/Resources.tsx` | Resource library | +| Stories | `pages/Stories.tsx` | Case studies/stories listing | +| Jobs | `pages/Jobs.tsx` | Career opportunities | +| Podcast | `pages/Podcast.tsx` | Podcast episodes | + +### Detail Pages + +| Page | Path | Purpose | +|------|------|---------| +| Article Detail | `pages/ArticleDetail.tsx` | Individual article view | +| Job Detail | `pages/JobDetail.tsx` | Job posting details | +| Story Detail | `pages/StoryDetail.tsx` | Individual story/case study | +| Webinar Detail | `pages/WebinarDetail.tsx` | Webinar information | + +## Design System + +### Branding +- **Custom Fonts:** + - Bermia (Display font for titles) + - Bornia (Sans-serif for body text) + +- **Color Palette (Ocobo Brand):** + - Dark: #212323 + - Yellow: #F1CF25 (Light: #FFFCEE) + - Mint: #9ADBBA (Light: #EBFDF5) + - Sky: #99D1DF (Light: #F0F9FB) + - Coral: #FE9C87 (Light: #FFF5F2) + - Gray: #F5F5F5 + +### Styling Approach +- **Framework:** Tailwind CSS (via CDN) +- **Custom Configuration:** Extends Tailwind with custom colors and fonts +- **Font Strategy:** Self-hosted custom fonts with fallbacks + +## Component Organization + +``` +components/ +├── Button.tsx # Reusable button component +├── Footer.tsx # Site footer +├── Navbar.tsx # Navigation header +├── NewsletterWidget.tsx # Newsletter subscription +└── ServiceCard.tsx # Service display card + +pages/ +├── Home.tsx # Landing page +├── About.tsx # About page +├── Contact.tsx # Contact page +├── Services.tsx # Services listing +├── Method.tsx # Methodology +├── Partners.tsx # Partners page +├── Studio.tsx # Studio page +├── Resources.tsx # Resources library +├── Stories.tsx # Stories listing +├── Jobs.tsx # Jobs listing +├── Podcast.tsx # Podcast page +├── ArticleDetail.tsx # Article detail view +├── JobDetail.tsx # Job detail view +├── StoryDetail.tsx # Story detail view +└── WebinarDetail.tsx # Webinar detail view +``` + +## Reusability Analysis + +### Highly Reusable Components (5) +- Button +- Footer +- Navbar +- NewsletterWidget +- ServiceCard + +### Page-Specific Components (15) +All page components are route-specific implementations. + +## Patterns Identified + +1. **Component-Based Architecture:** Clear separation between reusable components and page-specific views +2. **Routing Structure:** Dedicated pages for main sections with detail pages for content +3. **Design System:** Centralized branding with custom color palette and typography +4. **Responsive Design:** Tailwind CSS for responsive utilities + +## Notes + +- This is a pattern-based scan. For detailed component APIs, props, and implementation details, perform a deep scan. +- Component count: 20 total (5 reusable + 15 pages) +- All components use TypeScript for type safety +- Design system is well-defined with custom branding diff --git a/docs/data-models.md b/docs/data-models.md new file mode 100644 index 0000000..bbe094f --- /dev/null +++ b/docs/data-models.md @@ -0,0 +1,92 @@ +# Data Models + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React + TypeScript) +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based) + +## Overview + +This document catalogs the data models and TypeScript interfaces discovered in the project. + +## Type Definitions Location + +**Primary Types File:** `types.ts` + +## Identified Data Models + +### ThemeColor (Enum) +- **Location:** `types.ts:1` +- **Type:** Enumeration +- **Purpose:** Theme color definitions for the application +- **Usage:** Likely used for branding and UI theming + +### NavItem (Interface) +- **Location:** `types.ts:9` +- **Type:** Interface +- **Purpose:** Navigation item structure +- **Usage:** Defines navigation menu items for Navbar component +- **Related Components:** Navbar + +### ServiceItem (Interface) +- **Location:** `types.ts:14` +- **Type:** Interface +- **Purpose:** Service data structure +- **Usage:** Represents individual services displayed in the application +- **Related Components:** ServiceCard, Services page + +### StatItem (Interface) +- **Location:** `types.ts:21` +- **Type:** Interface +- **Purpose:** Statistics/metrics data structure +- **Usage:** Likely for displaying company statistics or metrics + +## Data Architecture + +### Frontend Data Management +- **Type System:** TypeScript for compile-time type safety +- **Data Structures:** Interface-based definitions +- **Enumerations:** Used for fixed value sets (ThemeColor) + +### Integration Points +- **API Integration:** Google Gemini API + - Configured via environment variable: `GEMINI_API_KEY` + - Defined in: `vite.config.ts` + +## Type Safety Approach + +1. **Centralized Types:** All shared types defined in `types.ts` +2. **Component Props:** TypeScript interfaces for component properties +3. **API Responses:** Typed interfaces for external API responses + +## Data Flow Patterns + +``` +User Input → Components → Type-Safe Props → API Calls → Typed Responses +``` + +## External Data Sources + +### Google Gemini API +- **Purpose:** AI integration +- **Configuration:** Environment-based API key +- **Integration Type:** REST API calls + +## Notes + +- This is a pattern-based quick scan +- For detailed field definitions and relationships, perform a deep scan +- Type definitions follow TypeScript best practices +- Centralized type management in single file for maintainability + +## Recommendations for Deep Scan + +When performing a deep scan, analyze: +1. Complete field definitions for each interface +2. Optional vs required fields +3. Nested object structures +4. Array types and collections +5. Type unions and intersections +6. Generic types usage +7. API response type mapping +8. Data validation patterns diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 0000000..278e4b9 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,323 @@ +# Development Guide + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React + TypeScript) +**Generated:** 2026-01-12 + +## Overview + +This guide provides instructions for setting up, developing, and building the Ocobo application. + +## Prerequisites + +### Required Software +- **Node.js** - JavaScript runtime (version not specified, recommend latest LTS) +- **npm** - Package manager (comes with Node.js) + +### Required Accounts/Keys +- **Google Gemini API Key** - For AI features integration + - Obtain from: Google AI Studio + - Required for: AI-powered functionality + +## Installation + +### 1. Clone Repository +```bash +git clone +cd prototype +``` + +### 2. Install Dependencies +```bash +npm install +``` + +**Installed Packages:** +- `react@19.2.3` - Frontend framework +- `react-dom@19.2.3` - React DOM rendering +- `react-router@7.11.0` - Routing library +- `react-router-dom@7.10.1` - React Router DOM bindings +- `lucide-react@0.561.0` - Icon library +- `typescript@5.8.2` - TypeScript compiler +- `vite@6.2.0` - Build tool +- `@vitejs/plugin-react@5.0.0` - Vite React plugin +- `@types/node@22.14.0` - Node.js type definitions + +### 3. Environment Setup + +Create a `.env.local` file in the project root: + +```bash +GEMINI_API_KEY=your_api_key_here +``` + +**Environment Variables:** +- `GEMINI_API_KEY` - Google Gemini API authentication key + +**Security Note:** Never commit `.env.local` to version control (already in `.gitignore`) + +## Development Workflow + +### Start Development Server + +```bash +npm run dev +``` + +**Dev Server Configuration:** +- **URL:** `http://localhost:3000` +- **Host:** `0.0.0.0` (accessible from network) +- **Hot Module Replacement (HMR):** Enabled +- **Fast Refresh:** React Fast Refresh enabled + +**What happens:** +- Vite dev server starts on port 3000 +- Application auto-reloads on file changes +- TypeScript compilation happens in real-time +- Source maps enabled for debugging + +### Build for Production + +```bash +npm run build +``` + +**Build Process:** +- TypeScript compilation +- React optimization and minification +- Asset bundling and optimization +- Output: `dist/` directory + +### Preview Production Build + +```bash +npm run preview +``` + +**Purpose:** Test production build locally before deployment + +## Project Structure + +### Source Code Organization + +``` +src/ +├── components/ # Reusable UI components +├── pages/ # Route-based page components +├── types.ts # TypeScript type definitions +├── App.tsx # Root application component +└── index.tsx # Application entry point +``` + +### Development Files +- `vite.config.ts` - Build configuration +- `tsconfig.json` - TypeScript configuration +- `package.json` - Dependencies and scripts + +## Development Commands + +### Available Scripts + +| Command | Purpose | Usage | +|---------|---------|-------| +| `npm run dev` | Start dev server | Development | +| `npm run build` | Build for production | Deployment prep | +| `npm run preview` | Preview production build | Testing | + +## TypeScript Configuration + +### Compiler Options +- **Target:** ES2022 +- **Module:** ESNext +- **JSX:** react-jsx (React 17+ transform) +- **Module Resolution:** bundler +- **Experimental Decorators:** Enabled +- **Path Aliases:** `@/*` → project root + +### Type Checking +```bash +# TypeScript will check types during: +- Development (Vite dev server) +- Build process (npm run build) +``` + +## Code Organization Guidelines + +### Component Structure +```typescript +// Pattern for functional components +import { FC } from 'react'; +import { ComponentProps } from './types'; + +export const ComponentName: FC = ({ prop1, prop2 }) => { + // Component logic + return ( + // JSX + ); +}; +``` + +### Type Definitions +- Define shared types in `types.ts` +- Use interfaces for component props +- Export types for reusability + +### Styling Approach +- **Primary:** Tailwind CSS utility classes +- **Custom Theme:** Configured in `index.html` +- **Colors:** Ocobo brand palette (dark, yellow, mint, sky, coral) +- **Fonts:** Bermia (display), Bornia (body) + +## API Integration + +### Environment-Based Configuration +```typescript +// Access API key in code: +const apiKey = process.env.GEMINI_API_KEY; +``` + +### API Client Pattern +- HTTP client: Fetch API (browser native) +- Request/Response typing via TypeScript interfaces +- Error handling with try-catch blocks + +## Common Development Tasks + +### Adding a New Page +1. Create component file in `/pages` + ```typescript + // pages/NewPage.tsx + export const NewPage = () => { + return
New Page Content
; + }; + ``` + +2. Add route in `App.tsx` (React Router configuration) + +### Creating a Reusable Component +1. Create component file in `/components` +2. Define TypeScript interface for props +3. Export component for use in pages + +### Adding New Types +1. Open `types.ts` +2. Add interface or enum +3. Export for use across application + +### Working with Environment Variables +1. Add variable to `.env.local` +2. Reference in `vite.config.ts` if needed +3. Access via `process.env.VARIABLE_NAME` + +## Debugging + +### Browser DevTools +- React DevTools extension recommended +- Source maps enabled in development +- Console logging for debugging + +### TypeScript Errors +- Check terminal output during `npm run dev` +- IDE integration (VS Code recommended) +- Type errors shown in editor + +## Performance Tips + +### Development +- Vite provides fast HMR +- React Fast Refresh preserves component state +- TypeScript compilation is incremental + +### Production +- Code splitting via React Router +- Asset optimization by Vite +- Tree shaking eliminates unused code + +## Troubleshooting + +### Common Issues + +**Port 3000 already in use:** +```bash +# Change port in vite.config.ts: +server: { port: 3001 } +``` + +**API key not working:** +- Verify `.env.local` exists +- Check variable name matches config +- Restart dev server after changing `.env.local` + +**TypeScript errors:** +- Run `npm install` to ensure all types are installed +- Check `tsconfig.json` for correct configuration +- Clear cache and restart: `rm -rf node_modules && npm install` + +## IDE Setup + +### Recommended: Visual Studio Code + +**Extensions:** +- ESLint +- Prettier +- TypeScript and JavaScript Language Features +- Tailwind CSS IntelliSense +- React Developer Tools + +**Settings:** +```json +{ + "typescript.tsdk": "node_modules/typescript/lib", + "editor.formatOnSave": true +} +``` + +## Testing Strategy + +### Current State +- No test framework configured (quick scan finding) +- Recommended: Vitest (pairs well with Vite) + +### Future Implementation +Consider adding: +- Unit tests for components +- Integration tests for pages +- E2E tests for critical flows + +## Deployment Preparation + +### Pre-Deployment Checklist +- [ ] Run `npm run build` successfully +- [ ] Test production build with `npm run preview` +- [ ] Verify environment variables for production +- [ ] Check API keys are configured for production environment +- [ ] Review build output in `dist/` + +### Build Output +- **Directory:** `dist/` +- **Contents:** Optimized HTML, CSS, JS, and assets +- **Ready for:** Static hosting (Vercel, Netlify, etc.) + +## External Resources + +### Documentation Links +- [React Documentation](https://react.dev) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/) +- [Vite Guide](https://vitejs.dev/guide/) +- [React Router](https://reactrouter.com) +- [Tailwind CSS](https://tailwindcss.com/docs) + +### API Documentation +- [Google Gemini API](https://ai.google.dev/docs) + +## Getting Help + +- Check project README.md +- Review generated documentation in `/docs` +- Consult official framework documentation + +## Notes + +- This guide is generated from pattern analysis (quick scan) +- For detailed workflow specifics, consult team documentation +- Update this guide as development practices evolve diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..462e3e4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,397 @@ +# Ocobo Project Documentation Index + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React SPA) +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based analysis) + +--- + +## Canonical agent entry + +This file is the canonical entry point for AI agents. Share this file first, then include the task-specific docs listed below. + +--- + +## 📋 Quick Reference + +| Attribute | Value | +|-----------|-------| +| **Repository Type** | Monolith | +| **Primary Language** | TypeScript 5.8.2 | +| **Framework** | React 19.2.3 | +| **Build Tool** | Vite 6.2.0 | +| **Architecture** | Component-Based SPA | +| **Components** | 20 total (5 reusable + 15 pages) | +| **Entry Point** | `index.tsx` | +| **Dev Server** | http://localhost:3000 | + +### Technology Stack Summary + +- **Frontend:** React 19 + TypeScript 5 +- **Routing:** React Router 7 +- **Styling:** Tailwind CSS + Custom Design System +- **Build:** Vite 6 +- **AI Integration:** Google Gemini API +- **Icons:** Lucide React + +--- + +## 🚀 Quick Start + +```bash +# Install dependencies +pnpm install + +# Setup environment +echo "GEMINI_API_KEY=your_key" > .env.local + +# Start development +pnpm run dev +``` + +**Access:** http://localhost:3000 + +--- + +## 📚 Generated Documentation + +### Core Documentation + +#### [Project Overview](./project-overview.md) +High-level project summary, purpose, technology stack, and current state assessment. +**Use this for:** Understanding the project at a glance, executive summaries. + +#### [Architecture Document](./architecture.md) +Comprehensive architecture overview including patterns, technology decisions, and scalability considerations. +**Use this for:** Understanding system design, planning integrations, architectural decisions. + +#### [Source Tree Analysis](./source-tree-analysis.md) +Annotated directory structure with explanations of critical folders and entry points. +**Use this for:** Navigating the codebase, understanding file organization. + +### Component & Code Documentation + +#### [Component Inventory](./component-inventory.md) +Complete catalog of all UI components (5 reusable + 15 pages) with organization patterns and design system details. +**Use this for:** Finding existing components, avoiding duplication, understanding UI patterns. + +#### [Data Models](./data-models.md) +TypeScript interfaces and type definitions (ThemeColor, NavItem, ServiceItem, StatItem). +**Use this for:** Understanding data structures, extending types, API response typing. + +### Integration & APIs + +#### [API Architecture](./api-architecture.md) +External integrations (Google Gemini API), state management patterns, and data flow. +**Use this for:** API integration patterns, state management approach, external services. + +### Development Resources + +#### [Development Guide](./development-guide.md) +Setup instructions, development workflow, commands, troubleshooting, and common tasks. +**Use this for:** Onboarding developers, development workflow, build and deployment prep. + +--- + +## 📖 Existing Documentation + +### Original Project Files + +- **[README.md](../README.md)** - Original project documentation with quick start guide + - Prerequisites: Node.js + - Setup: pnpm install, configure GEMINI_API_KEY + - Run: pnpm run dev + - AI Studio link included + +--- + +## 🏗️ Project Structure Overview + +``` +prototype/ +├── components/ # 5 Reusable UI components +│ ├── Button.tsx +│ ├── Footer.tsx +│ ├── Navbar.tsx +│ ├── NewsletterWidget.tsx +│ └── ServiceCard.tsx +│ +├── pages/ # 15 Route-based pages +│ ├── Home.tsx ⭐ Landing page +│ ├── About.tsx +│ ├── Contact.tsx +│ ├── Services.tsx +│ ├── Method.tsx +│ ├── Partners.tsx +│ ├── Studio.tsx +│ ├── Resources.tsx +│ ├── Stories.tsx +│ ├── Jobs.tsx +│ ├── Podcast.tsx +│ ├── ArticleDetail.tsx +│ ├── JobDetail.tsx +│ ├── StoryDetail.tsx +│ └── WebinarDetail.tsx +│ +├── fonts/ # Custom Bermia & Bornia fonts +├── docs/ # This documentation +├── App.tsx ⭐ Root component +├── index.tsx ⭐ Entry point +├── index.html ⭐ HTML bootstrap +├── types.ts # Type definitions +├── vite.config.ts # Build config +└── package.json # Dependencies +``` + +--- + +## 🎯 Common Use Cases + +### For New Features Development + +1. **Read:** [Architecture Document](./architecture.md) - Understand system design +2. **Check:** [Component Inventory](./component-inventory.md) - Reuse existing components +3. **Review:** [Data Models](./data-models.md) - Extend types appropriately +4. **Follow:** [API Architecture](./api-architecture.md) - Match integration patterns + +### For Brownfield PRD Creation + +1. Start with [Project Overview](./project-overview.md) for context +2. Reference [Architecture Document](./architecture.md) for constraints +3. Use [Component Inventory](./component-inventory.md) to identify reusable elements +4. Check [Data Models](./data-models.md) for existing data structures + +### For Developer Onboarding + +1. Read [README.md](../README.md) for quick start +2. Follow [Development Guide](./development-guide.md) for detailed setup +3. Review [Source Tree Analysis](./source-tree-analysis.md) for codebase navigation +4. Explore [Component Inventory](./component-inventory.md) to understand UI structure + +### For AI-Assisted Development + +**Provide this index.md to AI agents** as the canonical entry point, along with specific documentation files based on the task: + +- **UI Changes:** Component Inventory + Architecture +- **API Integration:** API Architecture + Data Models +- **New Pages:** Component Inventory + Source Tree Analysis +- **Refactoring:** Architecture + Source Tree Analysis + +--- + +## 🔧 Development Commands + +| Command | Purpose | +|---------|---------| +| `pnpm install` | Install dependencies | +| `pnpm run dev` | Start dev server (port 3000) | +| `pnpm run build` | Build for production | +| `pnpm run preview` | Preview production build | + +--- + +## 🌐 External Integrations + +### Google Gemini API +- **Purpose:** AI-powered features +- **Configuration:** Set `GEMINI_API_KEY` in `.env.local` +- **Details:** [API Architecture](./api-architecture.md) + +### CDN Resources +- Tailwind CSS (styling framework) +- Google Fonts (Inter fallback) +- Custom fonts (Bermia, Bornia from ocobo.co) + +--- + +## 🎨 Design System + +### Ocobo Brand Colors +- **Dark:** #212323 (primary text) +- **Yellow:** #F1CF25 (brand accent) +- **Mint:** #9ADBBA (secondary) +- **Sky:** #99D1DF (tertiary) +- **Coral:** #FE9C87 (highlight) +- **Gray:** #F5F5F5 (backgrounds) + +### Typography +- **Bermia** - Display font for headings (Black 900) +- **Bornia** - Sans-serif for body (Regular 400, Bold 700) + +--- + +## 📊 Project Metrics + +- **Total Components:** 20 (5 reusable + 15 pages) +- **TypeScript Files:** 23 +- **Dependencies:** 7 production, 4 development +- **Lines of Code:** ~1000+ (estimated) +- **Build Tool:** Vite 6.2.0 +- **Tests:** Vitest configured, coverage not configured + +--- + +## ⚡ Getting Started Guide + +### For Developers + +1. **Clone & Setup** + ```bash + git clone + cd prototype + pnpm install + ``` + +2. **Configure Environment** + ```bash + # Create .env.local with your Gemini API key + echo "GEMINI_API_KEY=your_api_key_here" > .env.local + ``` + +3. **Start Development** + ```bash + pnpm run dev + # Open http://localhost:3000 + ``` + +4. **Read Documentation** + - Start with [Development Guide](./development-guide.md) + - Review [Component Inventory](./component-inventory.md) + - Understand [Architecture](./architecture.md) + +### For Product Managers / Analysts + +1. Read [Project Overview](./project-overview.md) for high-level understanding +2. Review [Architecture Document](./architecture.md) for technical constraints +3. Check [Component Inventory](./component-inventory.md) for existing capabilities +4. Reference this index when creating requirements + +### For AI Agents + +**Context Priority:** +1. This index.md (navigation) +2. [Architecture Document](./architecture.md) (system understanding) +3. [Component Inventory](./component-inventory.md) (UI patterns) +4. [Data Models](./data-models.md) (type system) +5. Task-specific documentation as needed + +--- + +## 🔍 Documentation Usage by Workflow + +### BMad Method Workflows + +This documentation supports the following BMad Method workflows: + +#### ✅ Completed: Phase 0 - Documentation +- **Workflow:** document-project +- **Output:** This documentation set +- **Status:** Complete (Quick Scan) + +#### 🔜 Next: Phase 1 - Analysis (Optional) +- **Workflow:** brainstorm-project +- **Context:** Use Project Overview and Architecture +- **Agent:** analyst + +#### 🔜 Next: Phase 2 - Planning +- **Workflow:** prd (Product Requirements Document) +- **Context:** Use all documentation as brownfield context +- **Agent:** pm + +For additional workflows, see: `_bmad-output/planning-artifacts/bmm-workflow-status.yaml` + +--- + +## 📁 Documentation Files Summary + +| File | Size | Purpose | Status | +|------|------|---------|--------| +| index.md | Master | Navigation & quick reference | ✅ Complete | +| project-overview.md | Overview | High-level project summary | ✅ Complete | +| architecture.md | Comprehensive | System architecture details | ✅ Complete | +| component-inventory.md | Catalog | UI components reference | ✅ Complete | +| data-models.md | Technical | TypeScript type definitions | ✅ Complete | +| api-architecture.md | Technical | API & state management | ✅ Complete | +| development-guide.md | Practical | Setup & development workflow | ✅ Complete | +| source-tree-analysis.md | Reference | Directory structure | ✅ Complete | +| project-scan-report.json | Meta | Workflow state tracking | ✅ Complete | + +--- + +## 🎓 Learning Resources + +### Framework Documentation +- [React](https://react.dev) - UI framework +- [TypeScript](https://www.typescriptlang.org/docs/) - Type system +- [Vite](https://vitejs.dev) - Build tool +- [React Router](https://reactrouter.com) - Routing +- [Tailwind CSS](https://tailwindcss.com) - Styling + +### API Documentation +- [Google Gemini API](https://ai.google.dev/docs) - AI integration + +--- + +## 📝 Notes + +### About This Documentation + +- **Generation Method:** Quick scan (pattern-based, no deep file analysis) +- **Accuracy:** High-level patterns, structure, and configuration +- **Limitations:** Does not include detailed implementation analysis +- **Recommended:** Perform deep scan for comprehensive code-level documentation + +### For Deep Scan + +To generate more detailed documentation with implementation-level analysis: + +```bash +# Run document-project workflow again, choose option 2 (Deep Scan) +# This will analyze component implementations, state flows, and code patterns +``` + +### Maintenance + +- **Update Frequency:** Regenerate after major architectural changes +- **Manual Updates:** Add project-specific notes or clarifications as needed +- **Version Control:** Commit documentation changes with code changes + +--- + +## 🚀 Next Steps + +### Immediate (After Reading Docs) +- [ ] Setup development environment +- [ ] Run the application locally +- [ ] Explore component structure +- [ ] Review README.md for additional context + +### Short Term (Development) +- [ ] Expand test coverage (Vitest already configured) +- [ ] Implement additional component tests +- [ ] Add error boundaries +- [ ] Setup CI/CD pipeline + +### Long Term (Architecture) +- [ ] Consider state management library if complexity grows +- [ ] Implement code splitting for performance +- [ ] Add monitoring and analytics +- [ ] Setup staging environment + +--- + +## 📞 Getting Help + +- **Documentation Issues:** Regenerate docs with deep scan +- **Development Questions:** See [Development Guide](./development-guide.md) +- **Architecture Questions:** See [Architecture Document](./architecture.md) +- **Component Questions:** See [Component Inventory](./component-inventory.md) + +--- + +**🔖 Bookmark this page** - It's your primary entry point for all project documentation. + +--- + +*Generated by BMad Document Project Workflow | Scan Level: Quick | Date: 2026-01-12* diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..caac161 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,341 @@ +# Project Overview + +**Project Name:** Ocobo Revenue Operations Agency +**Type:** Web Application (React SPA) +**Status:** Prototype/Active Development +**Generated:** 2026-01-12 + +--- + +## Executive Summary + +Ocobo is a modern single-page web application showcasing revenue operations services. Built with React 19 and TypeScript, the application features a custom design system with branded colors and typography, and integrates AI capabilities through Google's Gemini API. The project represents a brownfield implementation with a clean component-based architecture optimized for maintainability and scalability. + +--- + +## Project Purpose + +**Primary Goal:** Showcase Ocobo's revenue operations services through an engaging, modern web experience. + +**Key Features:** +- Company information and methodology presentation +- Service catalog and case studies +- Resources library (articles, podcasts, webinars) +- Career opportunities portal +- AI-powered features (via Gemini API) +- Newsletter subscription functionality + +--- + +## Technology Stack Summary + +| Layer | Technologies | +|-------|-------------| +| **Frontend** | React 19.2.3, TypeScript 5.8.2 | +| **Build** | Vite 6.2.0 | +| **Routing** | React Router 7.10.1 | +| **Styling** | Tailwind CSS (CDN), Custom Design System | +| **Icons** | Lucide React 0.561.0 | +| **AI** | Google Gemini API | +| **Fonts** | Bermia (display), Bornia (body) | + +--- + +## Architecture Type + +**Classification:** Single Page Application (SPA) +**Pattern:** Component-Based Architecture +**Repository Type:** Monolith + +### Architecture Characteristics + +✅ **Client-Side Rendered:** React handles all rendering in browser +✅ **Component-Based:** Reusable UI components with clear separation +✅ **Type-Safe:** TypeScript for static type checking +✅ **Modern Build:** Vite for fast development and optimized production +✅ **Responsive:** Tailwind utilities for mobile-first design + +--- + +## Repository Structure + +``` +prototype/ +├── components/ # 5 reusable UI components +├── pages/ # 15 route-based page components +├── fonts/ # Custom Bermia & Bornia typography +├── docs/ # Generated project documentation +├── App.tsx # Root application component +├── index.tsx # Application entry point +├── index.html # HTML entry with styling config +├── types.ts # Centralized TypeScript definitions +└── vite.config.ts # Build configuration +``` + +--- + +## Key Components + +### Navigation & Layout +- **Navbar** - Main site navigation +- **Footer** - Site footer with links + +### UI Elements +- **Button** - Reusable button component +- **ServiceCard** - Service display cards +- **NewsletterWidget** - Email subscription form + +### Pages (15 total) + +**Main Pages:** +- Home, About, Contact, Services +- Method, Partners, Studio +- Resources, Stories, Jobs, Podcast + +**Detail Pages:** +- Article, Job, Story, Webinar detail views + +--- + +## Design System + +### Ocobo Brand Identity + +**Color Palette:** +- Dark (#212323) - Primary text +- Yellow (#F1CF25) - Brand accent +- Mint (#9ADBBA) - Secondary +- Sky (#99D1DF) - Tertiary +- Coral (#FE9C87) - Highlight +- Gray (#F5F5F5) - Backgrounds + +**Typography:** +- **Bermia** - Display font for impactful headings +- **Bornia** - Sans-serif for readable body text +- **Inter** - Fallback from Google Fonts + +--- + +## Development Setup + +### Quick Start + +```bash +# Install dependencies +npm install + +# Configure API key +echo "GEMINI_API_KEY=your_key_here" > .env.local + +# Start development server +npm run dev + +# Access at http://localhost:3000 +``` + +### Build Commands + +```bash +npm run build # Production build → dist/ +npm run preview # Test production build locally +``` + +--- + +## External Integrations + +### Google Gemini AI +- **Purpose:** AI-powered features +- **Type:** REST API +- **Auth:** API Key (environment variable) +- **Status:** Active integration + +### CDN Resources +- **Tailwind CSS:** Styling framework +- **Google Fonts:** Inter font family fallback +- **Custom Fonts:** Self-hosted from ocobo.co + +--- + +## Current State Assessment + +### Strengths ✅ + +- **Modern Stack:** React 19, TypeScript 5, Vite 6 +- **Clean Architecture:** Well-organized component structure +- **Type Safety:** Comprehensive TypeScript usage +- **Custom Branding:** Unique design system with custom fonts +- **Fast Development:** Vite provides excellent DX +- **AI Integration:** Gemini API for advanced features + +### Areas for Enhancement 📋 + +- **Testing:** No test framework configured +- **Documentation:** Code comments could be expanded +- **State Management:** No centralized state library (may be needed as app grows) +- **Error Handling:** Error boundaries and monitoring could be added +- **Performance:** Code splitting and lazy loading opportunities +- **Deployment:** CI/CD pipeline not visible (may exist elsewhere) + +--- + +## Project Metrics + +**Component Count:** 20 total +- 5 reusable components +- 15 page components + +**File Organization:** +- TypeScript/TSX files: 23 +- Configuration files: 4 +- Asset directories: 2 + +**External Dependencies:** 7 production + 4 development + +--- + +## Use Cases + +### Primary User Flows + +1. **Explore Services** + - Home → Services → ServiceCard interaction + - Method page for methodology understanding + +2. **Read Content** + - Resources → Articles/Webinars/Podcast + - Stories → Case studies and success stories + +3. **Connect & Engage** + - Contact form submission + - Newsletter subscription via widget + - Job application browsing + +4. **Learn About Company** + - About page for company information + - Partners page for ecosystem + - Studio for specialized services + +--- + +## Deployment + +### Hosting Recommendations + +**Optimal Platforms:** +- **Vercel** - Best integration with Vite/React +- **Netlify** - Simple deployment with git integration +- **AWS S3 + CloudFront** - Scalable static hosting +- **GitHub Pages** - Free for public repos + +### Production Checklist + +- [ ] Set `GEMINI_API_KEY` in hosting platform +- [ ] Configure custom domain +- [ ] Enable HTTPS +- [ ] Setup CDN for global distribution +- [ ] Configure environment variables +- [ ] Test production build locally first + +--- + +## Next Steps + +### For Development + +1. **Add Testing Framework** + - Install Vitest and React Testing Library + - Write component tests + - Add E2E tests with Playwright + +2. **Improve Performance** + - Implement route-based code splitting + - Add image optimization + - Enable service worker for offline support + +3. **Enhance Monitoring** + - Setup error tracking (Sentry) + - Add analytics (Plausible, Google Analytics) + - Implement performance monitoring + +4. **Documentation** + - Add JSDoc comments to components + - Create user documentation + - Document API integration patterns + +### For Deployment + +1. Run deep scan for detailed analysis +2. Setup CI/CD pipeline +3. Configure production environment +4. Deploy to hosting platform +5. Monitor and iterate + +--- + +## Documentation Links + +### Generated Documentation + +- **[Architecture Document](./architecture.md)** - Comprehensive architecture overview +- **[Component Inventory](./component-inventory.md)** - All UI components catalog +- **[Data Models](./data-models.md)** - TypeScript type definitions +- **[API Architecture](./api-architecture.md)** - API integration details +- **[Development Guide](./development-guide.md)** - Setup and workflow instructions +- **[Source Tree Analysis](./source-tree-analysis.md)** - Detailed directory structure + +### Project Files + +- **README.md** - Original project documentation +- **package.json** - Dependencies and scripts +- **tsconfig.json** - TypeScript configuration +- **vite.config.ts** - Build tool setup + +--- + +## AI-Assisted Development Notes + +### Using This Documentation for Brownfield PRD + +When planning new features or modifications: + +1. **Start with Architecture Document** + - Understand overall system design + - Identify integration points + - Review technology constraints + +2. **Reference Component Inventory** + - Identify reusable components + - Avoid duplicating existing components + - Maintain consistency with existing patterns + +3. **Check Data Models** + - Extend existing types rather than create new ones + - Maintain type safety across new features + - Follow established naming conventions + +4. **Review API Architecture** + - Understand existing integration patterns + - Maintain consistent API call structure + - Respect environment variable conventions + +### BMad Method Context + +This documentation was generated as part of the **BMad Method brownfield workflow**, specifically the **document-project** phase. It serves as the foundation for: + +- Creating comprehensive PRDs for new features +- Planning architectural enhancements +- Onboarding new developers +- AI agent context for development assistance + +--- + +## Contact & Resources + +**Project Location:** `/Users/jeromeboileux/projects/ocobo/prototype` +**Documentation:** `docs/` directory +**Generated:** 2026-01-12 by BMad Document Project Workflow + +--- + +*This overview provides a high-level understanding of the Ocobo project. For detailed technical information, refer to the linked documentation files.* diff --git a/docs/project-scan-report.json b/docs/project-scan-report.json new file mode 100644 index 0000000..993ba05 --- /dev/null +++ b/docs/project-scan-report.json @@ -0,0 +1 @@ +{"workflow_version":"1.2.0","timestamps":{"started":"2026-01-12T15:30:00Z","last_updated":"2026-01-12T15:42:00Z","completed":"2026-01-12T15:42:00Z"},"mode":"initial_scan","scan_level":"quick","project_root":"/Users/jeromeboileux/projects/ocobo/prototype","output_folder":"/Users/jeromeboileux/projects/ocobo/prototype/docs","completed_steps":[{"step":"step_1","status":"completed","timestamp":"2026-01-12T15:31:00Z","summary":"Classified as monolith with 1 part"},{"step":"step_2","status":"completed","timestamp":"2026-01-12T15:32:00Z","summary":"Found 1 existing docs"},{"step":"step_3","status":"completed","timestamp":"2026-01-12T15:33:00Z","summary":"Tech stack: React+Vite"},{"step":"step_4","status":"completed","timestamp":"2026-01-12T15:35:00Z","summary":"Conditional analysis complete, 3 files written"},{"step":"step_5","status":"completed","timestamp":"2026-01-12T15:37:00Z","summary":"Source tree documented"},{"step":"step_6","status":"completed","timestamp":"2026-01-12T15:38:00Z","summary":"Dev/deployment guides written"},{"step":"step_8","status":"completed","timestamp":"2026-01-12T15:39:00Z","summary":"Architecture docs written for 1 parts"},{"step":"step_9","status":"completed","timestamp":"2026-01-12T15:39:30Z","summary":"All supporting docs written"},{"step":"step_10","status":"completed","timestamp":"2026-01-12T15:40:00Z","summary":"Master index generated"},{"step":"step_11","status":"completed","timestamp":"2026-01-12T15:41:00Z","summary":"Validation and review complete"},{"step":"step_12","status":"completed","timestamp":"2026-01-12T15:42:00Z","summary":"Workflow complete"}],"current_step":"completed","findings":{"project_classification":"monolith, 1 part, React+TypeScript","existing_docs":"1 docs found","technology_stack":"React on TypeScript"},"project_types":[{"part_id":"main","project_type_id":"web","display_name":"Web Application"}],"outputs_generated":["project-scan-report.json","component-inventory.md","data-models.md","api-architecture.md","source-tree-analysis.md","development-guide.md","architecture.md","project-overview.md","index.md"],"resume_instructions":"Workflow completed successfully"} \ No newline at end of file diff --git a/docs/source-tree-analysis.md b/docs/source-tree-analysis.md new file mode 100644 index 0000000..97cf090 --- /dev/null +++ b/docs/source-tree-analysis.md @@ -0,0 +1,220 @@ +# Source Tree Analysis + +**Project:** Ocobo Revenue Operations Agency +**Type:** Web Application (React + TypeScript) +**Generated:** 2026-01-12 +**Scan Level:** Quick (pattern-based) + +## Overview + +This document provides an annotated directory tree showing the project structure and organization. + +## Project Root Structure + +``` +prototype/ +├── components/ # Reusable UI Components +│ ├── Button.tsx # Generic button component +│ ├── Footer.tsx # Site footer with links +│ ├── Navbar.tsx # Main navigation header +│ ├── NewsletterWidget.tsx # Newsletter subscription form +│ └── ServiceCard.tsx # Service display card component +│ +├── pages/ # Application Pages/Routes +│ ├── Home.tsx # ⭐ Landing page (entry point) +│ ├── About.tsx # About company page +│ ├── Contact.tsx # Contact form page +│ ├── Services.tsx # Services overview +│ ├── Method.tsx # Methodology page +│ ├── Partners.tsx # Partners information +│ ├── Studio.tsx # Studio services page +│ ├── Resources.tsx # Resource library +│ ├── Stories.tsx # Case studies listing +│ ├── Jobs.tsx # Career opportunities +│ ├── Podcast.tsx # Podcast episodes +│ ├── ArticleDetail.tsx # Individual article view +│ ├── JobDetail.tsx # Job posting details +│ ├── StoryDetail.tsx # Story/case study details +│ └── WebinarDetail.tsx # Webinar information page +│ +├── fonts/ # Custom Typography Assets +│ ├── bermia/ # Bermia display font +│ │ └── Bermia-Black.woff +│ └── bornia/ # Bornia sans-serif font +│ ├── Bornia-Regular.otf +│ └── Bornia-Bold.otf +│ +├── docs/ # 📚 Generated Documentation +│ ├── index.md # Master documentation index +│ ├── project-overview.md +│ ├── architecture.md +│ ├── component-inventory.md +│ ├── data-models.md +│ ├── api-architecture.md +│ ├── development-guide.md +│ ├── source-tree-analysis.md +│ └── project-scan-report.json +│ +├── _bmad/ # 🔧 BMad Method Framework +│ ├── bmm/ # BMad Method Module +│ └── core/ # Core BMad utilities +│ +├── App.tsx # ⭐ Root Application Component +├── index.tsx # ⭐ Application Entry Point +├── index.html # HTML entry with Tailwind config +├── types.ts # TypeScript type definitions +│ +├── vite.config.ts # ⚙️ Vite build configuration +├── tsconfig.json # TypeScript compiler config +├── package.json # Project dependencies +├── .env.local # 🔐 Environment variables (API keys) +├── .gitignore # Git ignore rules +├── README.md # Project documentation +└── metadata.json # Project metadata + +``` + +## Critical Directories Explained + +### `/components` +**Purpose:** Reusable UI components shared across pages +**Pattern:** Component-based architecture +**Key Files:** +- Navigation components (Navbar, Footer) +- UI elements (Button, ServiceCard) +- Widgets (NewsletterWidget) + +**Integration:** Imported and used by page components + +### `/pages` +**Purpose:** Route-based page components +**Pattern:** Each file represents a distinct route/view +**Organization:** +- Main pages (11 files): Home, About, Contact, etc. +- Detail pages (4 files): ArticleDetail, JobDetail, StoryDetail, WebinarDetail + +**Routing:** Managed by React Router (v7.10.1) + +### `/fonts` +**Purpose:** Custom typography assets for branding +**Contents:** +- Bermia (Display font - Black weight) +- Bornia (Sans-serif - Regular and Bold) + +**Loading:** Font-face declarations in `index.html` + +### `/docs` +**Purpose:** Generated project documentation +**Usage:** Reference for development and AI-assisted workflows +**Maintenance:** Auto-generated, should not be manually edited + +## Entry Points + +### 🎯 Primary Entry Point +**File:** `index.tsx` +**Purpose:** Application bootstrap +**Responsibilities:** +- Mount React app to DOM +- Initialize React Router +- Setup root-level providers + +### 🎯 Root Component +**File:** `App.tsx` +**Purpose:** Main application component +**Responsibilities:** +- Route configuration +- Layout structure +- Top-level state management + +### 🎯 HTML Entry +**File:** `index.html` +**Purpose:** HTML template and configuration +**Features:** +- Tailwind CSS CDN initialization +- Custom font loading +- Meta tags and SEO +- Root div mount point + +## Configuration Files + +### Build & Development +- **`vite.config.ts`**: Build tool configuration, dev server (port 3000), API key injection +- **`tsconfig.json`**: TypeScript compiler options, path aliases (`@/*`) +- **`package.json`**: Dependencies, scripts, project metadata + +### Environment +- **`.env.local`**: Environment variables (GEMINI_API_KEY) + +## File Organization Patterns + +### Component Naming +- **Convention:** PascalCase (e.g., `Button.tsx`, `ServiceCard.tsx`) +- **Extension:** `.tsx` for components with JSX +- **Location:** `/components` for reusable, `/pages` for routes + +### Type Definitions +- **File:** `types.ts` (centralized) +- **Pattern:** Interfaces and enums exported from single file +- **Usage:** Imported across components for type safety + +## Asset Management + +### Fonts +- **Strategy:** Self-hosted from production domain (`https://www.ocobo.co/fonts/`) +- **Formats:** WOFF (Bermia), OTF (Bornia) +- **Fallbacks:** Inter (Google Fonts), system sans-serif + +### Styles +- **Primary:** Tailwind CSS (CDN) +- **Custom:** Inline configuration in `index.html` +- **Theme:** Custom Ocobo color palette + +## Integration Points + +### External Services +1. **Google Gemini API** - AI features + - Config: `vite.config.ts` + - Key: `.env.local` + +2. **Tailwind CSS** - Styling framework + - Source: CDN (`https://cdn.tailwindcss.com`) + +3. **Google Fonts** - Inter font family + - Source: Google Fonts CDN + +## Notes + +- **Scan Level:** Quick (structure and patterns only) +- **Total Components:** 20 (5 reusable + 15 pages) +- **Total Lines:** ~1000+ (estimated from file count) +- **Organization:** Clean separation of concerns (components vs pages) + +## Architecture Highlights + +✅ **Well-Structured:** +- Clear component/page separation +- Centralized type definitions +- Environment-based configuration + +✅ **Modern Stack:** +- React 19 with hooks +- TypeScript for type safety +- Vite for fast development + +✅ **Design System:** +- Custom branding with fonts and colors +- Tailwind for utility classes +- Responsive design ready + +## Recommendations + +For deeper understanding: +1. Perform a **deep scan** to analyze: + - Component props and APIs + - State management patterns + - API call implementations + - Routing configuration details + +2. Review routing structure in `App.tsx` +3. Analyze component reusability patterns +4. Document state flow between components