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

   git clone <repository-url>
   cd poc
   

2. Start all services

   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

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

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:

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

Update Workflow Item:

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

   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)

   ./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):

   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)

   # 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.