Getting Started

This guide covers the minimum steps to clone, configure, and run the Stakeholder Agent System locally.

Prerequisites

Before you begin, ensure you have the required tools installed:

Tool	Version	Purpose
Node.js	v20+	Frontend runtime
Python	3.11+	Backend runtime
Docker	Latest stable	Containerization
PostgreSQL	15+	Database
Git	Latest	Version control

For complete development environment details, see Development Workflows.

Clone the Repositories

The project consists of separate frontend and backend repositories:

# Frontend application
git clone https://github.com/project-steak-holder/ai-frontend.git

# Backend AI service
git clone https://github.com/project-steak-holder/ai-backend.git

Backend Setup

Navigate to the backend directory:
```
cd ai-backend
```

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

curl https://uvm.astral.sh/install.sh | sh
uv sync

Configure environment variables:

Create a .env file with the required configuration:

DATABASE_URL=postgresql://user:password@localhost:5432/stakeholder_db
NEON_AUTH_SECRET=your_auth_secret
AI_PROVIDER_API_KEY=your_api_key

Run database migrations:
```
alembic upgrade head
```
Start the backend service:
```
uvicorn app.main:app --reload
```
The API will be available at http://localhost:8000.

Frontend Setup

Navigate to the frontend directory:
```
cd ai-frontend
```
Install dependencies:
```
npm install
```

Configure environment variables:

Create a .env file:

VITE_API_URL=http://localhost:8000
VITE_AUTH_DOMAIN=your_auth_domain

Start the development server:
```
npm run dev
```
The application will be available at http://localhost:5173.

Verify Installation

Open your browser to http://localhost:5173
Create a new account or log in
Start a new conversation to verify the system is working

Next Steps

Once you have the system running locally:

Goal	Documentation
Understand the system design	Architecture
Learn about the tech stack	Technology Stack
Start contributing code	Development Workflows
Work on a feature	Implementation Guidance
Write tests	Testing Strategy
Use the API	API Documentation
Troubleshoot issues	Troubleshooting
Contribute to the project	Contributing