PhoenixAIFlow Monorepo

AI-assisted development environment with React frontend and Kotlin backend, organized as a monorepo for streamlined development and testing.

🎉 Phase 1 Complete!

Status: ✅ Backend API + Frontend Integration operational

The backend REST API is fully functional with document CRUD operations, project management, and configuration endpoints. Both servers are running and ready for Phase 2 development.

Quick Links:

• 📋 Phase 1 Completion Report - Detailed test results and achievements
• 🧪 API Testing Guide - Complete API reference with examples
• 🗺️ Phase 2 Plan - Roadmap for next phase

Servers:

• Backend API: http://localhost:8080
• Frontend UI: http://localhost:3000

Project Structure

phoenixaiflow-combined/
├── apps/
│   ├── backend/          # Kotlin/Ktor backend service
│   └── frontend/         # React/TypeScript frontend
├── packages/             # Shared packages (future use)
├── integration-tests/    # E2E tests for full stack
├── .git/                 # Git repository
├── .gitignore           # Monorepo gitignore
├── package.json         # Root workspace configuration
└── README.md            # This file

Prerequisites

• Node.js 16+ and npm 8+
• Java 11+ (for Kotlin backend)
• Git

Getting Started

1. Install Dependencies

npm install

This will install dependencies for the frontend, integration tests, and shared packages.

2. Run Development Servers

Run both frontend and backend together:

npm run dev

Run individually:

# Frontend only (React dev server on :3000)
npm run dev:frontend

# Backend only (Ktor server on :8080)
npm run dev:backend

3. Build for Production

# Build both
npm run build

# Build individually
npm run build:frontend
npm run build:backend

Testing

Frontend Tests

npm run test:frontend

Backend Tests

npm run test:backend

Integration Tests (Frontend + Backend)

npm run test:integration

See integration-tests/README.md for more details on integration testing.

Project Details

Backend (apps/backend)

• Technology: Kotlin, Ktor, Gradle
• Port: 8080 (default)
• Entry point: com.ApplicationKt
• Build tool: Gradle with Kotlin DSL

See apps/backend/README.md for backend-specific documentation.

Frontend (apps/frontend)

• Technology: React 18, TypeScript, Tailwind CSS
• Port: 3000 (default)
• Build tool: react-scripts (Create React App)
• E2E Testing: Playwright

See apps/frontend/CLAUDE.md for detailed frontend architecture.

Monorepo Workspace

This project uses npm workspaces to manage multiple packages:

• apps/frontend - React frontend
• packages/* - Shared packages (future)
• integration-tests - E2E integration tests

Adding Shared Packages

To create a shared package that both frontend and backend can use:

1. Create a new directory in packages/
2. Add a package.json with a unique name
3. Reference it in other packages using "packageName": "workspace:*"

Development Workflow

Typical Development Flow

1. Start both servers: npm run dev
2. Make changes to frontend or backend
3. Run tests as you develop
4. Run integration tests before committing major features
5. Commit changes using git

Running Integration Tests

Integration tests verify that frontend and backend work together:

# Run integration tests
npm run test:integration

# Run with UI (interactive mode)
cd integration-tests && npm run test:ui

# Debug tests
cd integration-tests && npm run test:debug

Available Scripts

Script	Description
npm run dev	Start both frontend and backend
npm run dev:frontend	Start frontend only
npm run dev:backend	Start backend only
npm run build	Build both projects
npm run build:frontend	Build frontend only
npm run build:backend	Build backend only
npm run test	Run frontend and backend tests
npm run test:frontend	Run frontend tests
npm run test:backend	Run backend tests
npm run test:integration	Run integration tests
npm run clean	Clean all build artifacts

Git Setup

The repository is initialized with git and includes a comprehensive .gitignore that covers:

• Node.js/npm artifacts
• Gradle/Kotlin build files
• IDE configurations
• OS-specific files
• Test reports and coverage

Initial Commit

To make your first commit:

git add .
git commit -m "Initial monorepo setup with frontend and backend"

Adding Remote

To push to a remote repository:

git remote add origin <your-repo-url>
git branch -M main
git push -u origin main

Architecture Overview

Communication Flow

User → Frontend (React) → Backend API (Ktor) → Domain Logic → Response

Key Features

• Epic/Feature/Story hierarchy for work organization
• Real-time conversation interface with AI assistance
• Focus-based navigation system
• Workflow management for development stages
• Document rendering and viewing

Troubleshooting

Port Already in Use

If ports 3000 or 8080 are in use:

• Frontend: Set PORT=3001 before running
• Backend: Check apps/backend/src/main/resources/application.conf

Backend Won't Start

• Ensure Java 11+ is installed: java -version
• Clean and rebuild: npm run clean:backend && npm run build:backend

Frontend Build Issues

• Clear cache: npm run clean:frontend
• Reinstall dependencies: rm -rf node_modules package-lock.json && npm install

Integration Tests Failing

• Ensure both servers are running
• Check that ports 3000 and 8080 are accessible
• Review test reports in integration-tests/test-reports/

Contributing

1. Create a feature branch
2. Make your changes
3. Run tests: npm run test
4. Run integration tests: npm run test:integration
5. Commit with clear messages
6. Create a pull request

License

ISC