Getting Started with EASE

Welcome to EASE (Enterprise Architecture for Security and Extensibility)! This guide will help you get up and running quickly.

What is EASE?

EASE is a complete enterprise application platform that Fortune 200 companies can clone to build ANY business solution. Teams clone this repo and add ONLY their business logic - everything else is provided.

Core Value Proposition

Traditional Approach: 6-12 months to production EASE Approach: 2-3 months to production

EASE provides:

• ✅ Infrastructure setup
• ✅ Multi-tenancy support
• ✅ RBAC implementation
• ✅ Security best practices
• ✅ API Gateway configuration
• ✅ Observability stack
• ✅ Reusable framework code

You provide:

• 🎯 Your database tables
• 🎯 Your business logic
• 🎯 Your UI screens

Quick Start Paths

Choose your learning path based on your role:

🌱 New to EASE?

1. What is EASE? - Understand the platform (5 min read)
2. Architecture Overview - See the big picture (10 min read)
3. Your First Component - Build something! (30 min tutorial)
4. Multi-tenancy Guide - Understand tenant isolation (15 min read)

👨‍💻 Frontend Developer?

1. What is EASE? - Platform overview
2. Next.js Setup - Frontend architecture (coming soon)
3. Component Library - Using shadcn/ui components (coming soon)
4. API Integration - Calling backend services (coming soon)
5. RBAC in UI - Permission-based rendering (coming soon)

🔧 Backend Developer?

1. What is EASE? - Platform overview
2. Your First Component - End-to-end tutorial
3. Oracle Integration - Dapper and VPD (coming soon)
4. Multi-Tenancy Patterns - Tenant isolation strategies (coming soon)
5. RBAC Implementation - Role-based access control (coming soon)

🚀 DevOps Engineer?

1. What is EASE? - Platform overview
2. Local Setup - Docker Compose (coming soon)
3. Kong Gateway - API gateway configuration (coming soon)
4. Production Deployment - Kubernetes setup (coming soon)
5. Monitoring - Prometheus, Grafana, ELK (coming soon)

Installation & Setup

Prerequisites

Before you begin, ensure you have:

• Docker (20.10+) and Docker Compose (2.0+)
• Node.js (18+) for frontend development
• .NET SDK (8.0+) for backend development
• Python (3.11+) for AI chatbot development
• Git for version control

Quick Start (5 minutes)

# Clone the repository
git clone <repository-url>
cd ease/stackexplorer

# Start all services with Docker Compose
docker-compose up -d

# Wait for services to be ready (~60 seconds)
docker-compose ps

# Open StackExplorer in your browser
open http://localhost:3000

That's it! All services are now running:

• 🌐 Frontend: http://localhost:3000
• 🔌 Backend API: http://localhost:5000
• 🤖 Chatbot API: http://localhost:8000
• 🗄️ PostgreSQL: localhost:5432
• 💾 Redis: localhost:6379

Development Setup (Local)

For active development, you may want to run services individually:

Frontend Development

cd frontend
npm install
npm run dev
# Open http://localhost:3000

Create .env.local:

NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_CHATBOT_URL=http://localhost:8000
NEXT_PUBLIC_ENABLE_BACH=true

Backend Development

cd backend/StackExplorer.API
dotnet restore
dotnet run
# API available at http://localhost:5000
# Swagger docs at http://localhost:5000/swagger

Update appsettings.Development.json with your database connection.

Chatbot Development

cd chatbot
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
# API docs at http://localhost:8000/docs

First Steps After Setup

1. Explore StackExplorer

Open http://localhost:3000 and explore:

• Browse the homepage
• Check out the documentation
• Try the search functionality

2. Use BACH AI Assistant

Press Ctrl + / anywhere to open BACH, your AI assistant.

Try asking:

• "What is EASE?"
• "How do I implement multi-tenancy?"
• "Show me an example of a controller with RBAC"
• "Explain the authentication flow"

3. Browse API Documentation

• Backend API Swagger: http://localhost:5000/swagger
• Chatbot API docs: http://localhost:8000/docs

4. Check Service Health

# Frontend health
curl http://localhost:3000/api/health

# Backend health
curl http://localhost:5000/health

# Chatbot health
curl http://localhost:8000/health

Learning Path Recommendations

Week 1: Fundamentals

Day 1-2: Understanding EASE

• Read What is EASE?
• Review Architecture Overview
• Understand the technology stack

Day 3-4: Hands-On

• Complete Your First Component tutorial
• Explore the codebase
• Ask BACH questions

Day 5: Deep Dive

• Study Multi-tenancy Guide
• Understand VPD and tenant isolation
• Review security patterns

Week 2: Building Features

Day 1-2: Database & Backend

• Create your own entity
• Build repository and service
• Create API endpoints

Day 3-4: Frontend

• Build UI components
• Integrate with backend API
• Implement forms and validation

Day 5: Testing & Deployment

• Write unit tests
• Test API endpoints
• Deploy to staging environment

Essential Documentation

Must Read

1. What is EASE? - Core concepts and philosophy
2. Architecture Overview - System architecture and design
3. Your First Component - Hands-on tutorial

Important Topics

4. Multi-Tenancy - Tenant isolation strategies
5. RBAC Guide - Role-based access control (coming soon)
6. API Design Patterns - RESTful API best practices (coming soon)
7. Frontend Patterns - React component design (coming soon)

Reference

8. API Reference - Complete API documentation (coming soon)
9. Component Library - UI component showcase (coming soon)
10. Deployment Guide - Production deployment (coming soon)

Development Workflow

Typical Development Flow

1. Define Requirements

   • What feature are you building?
   • What data model do you need?
   • What permissions are required?

2. Database First

   • Create migration script
   • Define tables with multi-tenancy in mind
   • Add VPD policies

3. Backend Development

   • Create models and DTOs
   • Build repository layer
   • Implement service layer
   • Create API endpoints

4. Frontend Development

   • Design UI components
   • Integrate with API
   • Handle loading and error states

5. Testing

   • Unit tests for services
   • Integration tests for API
   • E2E tests for critical flows

6. Documentation

   • Add XML comments to code
   • Update API documentation
   • Create user guides if needed

Common Tasks

Create a New Entity

# 1. Create migration
cd database/migrations
touch 00X_create_my_table.sql

# 2. Create model
cd backend/StackExplorer.API/Models
touch MyEntity.cs

# 3. Create repository
cd ../Repositories
touch MyEntityRepository.cs

# 4. Create service
cd ../Services
touch MyEntityService.cs

# 5. Create controller
cd ../Controllers
touch MyEntityController.cs

# 6. Create frontend page
cd frontend/app
mkdir my-entities
touch my-entities/page.tsx

Add a New API Endpoint

[HttpGet]
public async Task<IActionResult> GetAll()
{
    var tenantId = GetTenantId();
    var entities = await _service.GetAllAsync(tenantId);
    return Ok(entities);
}

Create a Frontend Component

'use client';

export default function MyComponent() {
  const [data, setData] = useState([]);

  useEffect(() => {
    fetch('/api/my-endpoint')
      .then(res => res.json())
      .then(setData);
  }, []);

  return <div>{/* Your UI */}</div>;
}

Troubleshooting

Services Won't Start

# Check if ports are available
lsof -i :3000  # Frontend
lsof -i :5000  # Backend
lsof -i :8000  # Chatbot

# Check Docker logs
docker-compose logs -f

# Restart services
docker-compose down
docker-compose up -d

Database Connection Errors

# Check PostgreSQL is running
docker-compose ps postgres

# View PostgreSQL logs
docker-compose logs postgres

# Connect to database manually
docker-compose exec postgres psql -U ease -d stackexplorer

Frontend Build Errors

# Clear cache and reinstall
cd frontend
rm -rf .next node_modules
npm install
npm run dev

API 401 Unauthorized

• Ensure you're authenticated (valid JWT token)
• Check token expiration
• Verify CORS settings in backend

Getting Help

Use BACH AI Assistant

Press Ctrl + / anywhere and ask questions:

• "How do I implement X?"
• "Show me an example of Y"
• "Explain how Z works"

Documentation Resources

• StackExplorer Portal: http://localhost:3000
• Architecture Docs: architecture/overview.md
• API Reference: http://localhost:5000/swagger

Community & Support

• Create issues for bugs
• Submit feature requests
• Ask questions in discussions
• Contribute improvements

Next Steps

Ready to start building? Choose your path:

🎯 Hands-On Learner

→ Jump to Your First Component

📚 Concept-First Learner

→ Read Architecture Overview

🏗️ Architecture Focused

→ Study Multi-Tenancy Guide

🔐 Security Focused

→ Learn about RBAC (coming soon)

Quick Reference

Service URLs

Keyboard Shortcuts

Common Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild services
docker-compose up -d --build

# Run frontend dev server
cd frontend && npm run dev

# Run backend dev server
cd backend/StackExplorer.API && dotnet run

# Run chatbot dev server
cd chatbot && uvicorn main:app --reload

Let's build something amazing with EASE! 🚀

Start with: Your First Component →