sciagent/README.md

Initiative Management System

The platform consists of two main services:

- **Frontend**: React-based web application with TypeScript and Vite
- **Backend**: FastAPI-based REST API with Python 3.11
- **AI Integration**: Ollama-powered document analysis and compliance checking

## Project Structure

```
poc/
├── fe0/                    # Frontend service
│   ├── src/               # React application source
│   ├── public/            # Static assets
│   ├── package.json       # Node.js dependencies
│   └── Dockerfile         # Frontend container
├── be0/                   # Backend service
│   ├── src/               # Python application source
│   ├── main.py           # FastAPI application entry point
│   ├── requirements.txt  # Python dependencies
│   └── Dockerfile        # Backend container
├── assets/               # Shared resources and data
└── docker-compose.yml    # Service orchestration
```

## Prerequisites

- Docker 20.10+
- Docker Compose 2.0+
- Git

## Quick Start

1. **Clone and setup**
   ```bash
   git clone <repository-url>
   cd poc
   ```

2. **Start all services**
   ```bash
   docker-compose up --build
   ```

3. **Access the application**
   - **Frontend**: http://localhost:8081
   - **Backend API**: http://localhost:4402
   - **API Documentation**: http://localhost:4402/docs

## Development Setup

### Frontend Development

```bash
cd fe0
npm install
npm run dev
```

**Available Scripts:**
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build
- `npm run lint` - Run ESLint

**Technology Stack:**
- React 18 with TypeScript
- Vite for build tooling
- Tailwind CSS for styling
- shadcn/ui component library
- React Router for navigation
- TanStack Query for state management

### Backend Development

```bash
cd be0
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 4402 --reload
```

**Technology Stack:**
- FastAPI framework
- Python 3.11
- Pydantic for data validation
- LangChain for AI workflows
- Ollama for local AI models
- PDF processing with PyPDF and Docling

## API Documentation

### Core Endpoints

#### Workflow Management
- `POST /workflows` - Initialize new compliance workflow
- `GET /workflows/{workflow_id}` - Retrieve workflow status
- `PUT /workflows/{workflow_id}/items` - Update workflow items
- `POST /workflows/{workflow_id}/approvals` - Submit approvals
- `GET /workflows/{workflow_id}/report` - Generate status reports
- `POST /workflows/{workflow_id}/advance` - Progress to next phase

#### Document Processing
- `POST /upload_document` - Upload and parse documents
- `POST /get_page` - Retrieve specific document pages
- `POST /test_ollama` - Test AI model connectivity

#### System Health
- `GET /health` - Service health check
- `GET /` - API information and available endpoints

### Request/Response Examples

**Create Workflow:**
```json
POST /workflows
{
  "project_name": "ISO 27001 Implementation",
  "project_description": "Implement ISO 27001 controls",
  "records_officer_email": "officer@company.com"
}
```

**Update Workflow Item:**
```json
PUT /workflows/{workflow_id}/items
{
  "item_id": 1,
  "status": "completed",
  "comment": "Implementation completed",
  "updated_by": "john.doe@company.com"
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GENERIC_TIMEZONE`` | Application timezone | `UTC` |
| `NVIDIA_VISIBLE_DEVICES` | GPU access for AI models | `all` |
| `NVIDIA_DRIVER_CAPABILITIES` | GPU capabilities | `compute,utility` |

### Docker Network Configuration

Services communicate via a custom Docker network (`profyt-net`) with static IP addressing:
- Frontend: `192.168.42.20`
- Backend: `192.168.42.22`

## Features

### Compliance Management
- **ISO 27001** compliance tracking and reporting
- **Records Management** integration workflows
- **Risk Assessment** tools and dashboards
- **Document Processing** with AI-powered analysis

### Workflow Engine
- Multi-phase compliance workflows
- Approval management system
- Progress tracking and reporting
- Integration with external systems

### AI-Powered Analysis
- Document parsing and content extraction
- Compliance gap analysis
- Automated report generation
- Natural language processing for policy analysis

## Deployment

### Production Deployment

On the **application host** (SSH), from the repository root:

1. **Secrets & config**
   ```bash
   cp .env.example .env
   # Edit .env: PUBLIC_HOST, ports, MinIO and Postgres credentials (openssl rand -base64 32).
   # Never commit `.env`. Postgres user/password apply only on FIRST empty DB volume — see `.env.example`.
   ./scripts/verify-prod-env.sh
   ```

2. **Deploy (pull, build, recreate containers)**
   ```bash
   ./scripts/deploy-prod.sh
   # Air-gapped / no registry pull:
   # ./scripts/deploy-prod.sh --no-pull
   ```

   Or manually (must pass `/.env` explicitly if it is not named `.env` next to the compose file):
   ```bash
   docker compose --env-file .env -f docker-compose.prod.yml pull
   docker compose --env-file .env -f docker-compose.prod.yml up -d --build --remove-orphans
   ```

3. **Smoke checks** (`FE_PORT` and API port come from `.env` / compose; API is `127.0.0.1:4402` in prod compose)
   ```bash
   # Replace 8081 with the FE_PORT value in .env when different.
   curl -sf http://127.0.0.1:8081/
   curl -sf http://127.0.0.1:4402/health
   ```

### Scaling Considerations

- **Frontend**: Stateless, horizontally scalable
- **Backend**: Consider database persistence for production
- **AI Models**: GPU requirements for optimal performance
- **Storage**: Implement proper file storage for documents

## Monitoring and Logging

### Application Logs
- Frontend logs: Available via Docker logs
- Backend logs: Stored in `be0/logs/` directory
- System logs: `docker-compose logs [service-name]`

### Health Monitoring
- Health check endpoints available
- Docker health checks configured
- Log aggregation recommended for production

## Security Considerations

### Current Implementation
- CORS enabled for cross-origin requests
- Input validation via Pydantic models
- File upload restrictions

### Production Recommendations
- Implement authentication/authorization
- Add rate limiting
- Enable HTTPS/TLS
- Implement proper secret management
- Add audit logging

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines
- Follow TypeScript best practices
- Write comprehensive tests
- Update documentation for new features
- Follow conventional commit messages

## License

This project is licensed under the terms specified in the LICENSE file.