Skip to content

Commit c273f00

Browse files
George SibbleGeorge Sibble
George Sibble
authored and
George Sibble
committed
Updated Readme
1 parent 3018f2a commit c273f00

1 file changed

Lines changed: 167 additions & 133 deletions

File tree

‎README.md‎

Lines changed: 167 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,61 @@ Written with pride solo by George Sibble in about 60 days.
88

99
- [Project Overview](#project-overview)
1010
- [Architecture](#architecture)
11-
- [Prerequisites](#prerequisites)
12-
- [Local Development Setup](#local-development-setup)
13-
- [Running Tests](#running-tests)
14-
- [Deployment](#deployment)
1511
- [Project Structure](#project-structure)
1612
- [Code Organization](#code-organization)
1713
- [Key Features](#key-features)
1814
- [Security](#security)
15+
- [Prerequisites](#prerequisites)
16+
- [Local Development Setup](#local-development-setup)
17+
- [Running Tests](#running-tests)
18+
- [Deployment](#deployment)
1919
- [Contributing](#contributing)
2020
- [License](#license)
2121

2222
## Project Overview
2323

24-
ODAI is a sophisticated AI assistant that integrates with 30+ third-party services including:
24+
ODAI is a production-grade AI assistant platform that pushes the boundaries of what's possible with modern AI technology. Built from the ground up in just 60 days, it demonstrates sophisticated software engineering across multiple cutting-edge domains.
25+
26+
### Technical Highlights
27+
28+
**Advanced Agent Architecture**
29+
- Implements OpenAI's latest agent framework with intelligent tool orchestration across 30+ third-party services
30+
- Multi-agent system with specialized orchestrators for different interaction modes (chat, voice)
31+
- Context-aware tool selection that dynamically routes requests to the appropriate service connector
32+
- Automatic conversation title generation and semantic understanding
33+
34+
**Real-Time Streaming Infrastructure**
35+
- Custom WebSocket implementation enabling character-by-character AI response streaming
36+
- Live tool call visualization showing users exactly what the AI is doing in real-time
37+
- Sophisticated connection lifecycle management with automatic reconnection and state preservation
38+
- Bidirectional communication supporting both text and voice data streams
39+
40+
**Next-Generation Voice Interface**
41+
- Full-duplex voice conversations using Twilio WebRTC integration
42+
- Real-time audio processing and streaming to OpenAI's speech models
43+
- Seamless transition between text and voice modalities within the same conversation
44+
- Production-ready voice call handling with sophisticated error recovery
45+
46+
**Enterprise-Grade Security**
47+
- Google Cloud KMS-based encryption for all sensitive tokens and credentials
48+
- User-specific encryption keys ensuring data isolation
49+
- OAuth 2.0 flows for 15+ services with secure state management
50+
- Production-enforced authentication middleware with Firebase integration
51+
52+
**Comprehensive Integration Ecosystem**
53+
The platform seamlessly connects with 30+ services across multiple domains:
2554
- **Financial Services**: Plaid (banking), Finnhub (stocks), CoinMarketCap (crypto), Alpaca (trading)
2655
- **Travel & Transportation**: Amadeus (flights), FlightAware, Amtrak, TripAdvisor
2756
- **Productivity**: Gmail, Google Calendar/Docs, Slack, Evernote, Twilio
2857
- **Shopping & Commerce**: Amazon, Google Shopping, Yelp, Ticketmaster
2958
- **Information**: Google Search/News, Weather API, Web scraping
3059

31-
The platform supports real-time chat via WebSocket, voice interactions through Twilio, and secure OAuth-based authentication.
60+
**Production-Ready Engineering**
61+
- 700+ tests achieving 90%+ code coverage across the entire codebase
62+
- Parallel test execution with advanced test runner supporting multiple configurations
63+
- Google App Engine deployment with auto-scaling (2-20 instances)
64+
- Comprehensive error handling, logging, and monitoring
65+
- Clean layered architecture separating concerns across API, Service, Integration, and Data layers
3266

3367
## Architecture
3468

@@ -62,6 +96,133 @@ The application follows a clean, layered architecture:
6296
└─────────────────────────────────────────┘
6397
```
6498

99+
## Project Structure
100+
101+
```
102+
backend/
103+
├── api.py # Main FastAPI application entry point
104+
├── requirements.txt # Production dependencies
105+
├── test_requirements.txt # Testing dependencies
106+
├── app.yaml # Development deployment config
107+
├── prod.yaml # Production deployment config
108+
├── run_tests.py # Custom test runner
109+
├── CLAUDE.md # AI assistant guidance
110+
│
111+
├── routers/ # API route handlers
112+
│ ├── google.py # Google OAuth endpoints
113+
│ ├── plaid.py # Financial account linking
114+
│ ├── twilio/ # Voice call handling
115+
│ └── app_voice.py # In-app voice interactions
116+
│
117+
├── services/ # Business logic layer
118+
│ ├── auth_service.py # Authentication and authorization
119+
│ ├── chat_service.py # Chat management and AI integration
120+
│ └── location_service.py # Geolocation services
121+
│
122+
├── websocket/ # WebSocket implementation
123+
│ ├── connection_manager.py # Connection lifecycle
124+
│ └── websocket_handler.py # Chat interaction flow
125+
│
126+
├── firebase/ # Data models and persistence
127+
│ ├── models/ # Firestore document models
128+
│ │ ├── user.py # User profiles and settings
129+
│ │ ├── chat.py # Chat conversations
130+
│ │ ├── tokens.py # OAuth token storage
131+
│ │ └── ...
132+
│ └── firebase_init.py # Firebase initialization
133+
│
134+
├── connectors/ # Third-party integrations
135+
│ ├── orchestrator.py # Main AI agent orchestrator
136+
│ ├── voice_orchestrator.py # Voice-specific orchestrator
137+
│ ├── plaid_agent.py # Financial services
138+
│ ├── gmail_agent.py # Email integration
139+
│ └── ... # 30+ other integrations
140+
│
141+
└── tests/ # Test suite
142+
├── test_*.py # Test files mirror source structure
143+
└── conftest.py # pytest configuration
144+
```
145+
146+
## Code Organization
147+
148+
### Design Patterns
149+
150+
1. **Layered Architecture**: Clear separation between API, Service, Integration, and Data layers
151+
2. **Dependency Injection**: Services receive dependencies via constructors
152+
3. **Repository Pattern**: Firebase models abstract database operations
153+
4. **Agent-Based Architecture**: Specialized agents for different domains
154+
5. **Async/Await**: Consistent async patterns throughout
155+
156+
### Key Conventions
157+
158+
- **File Naming**: Snake_case for Python files (e.g., `auth_service.py`)
159+
- **Class Naming**: PascalCase for classes (e.g., `AuthService`)
160+
- **Function Naming**: Snake_case for functions (e.g., `validate_token()`)
161+
- **Test Files**: Prefix with `test_` (e.g., `test_auth_service.py`)
162+
- **Environment Variables**: UPPER_SNAKE_CASE (e.g., `OPENAI_API_KEY`)
163+
164+
### Adding New Features
165+
166+
1. **New API Endpoint**:
167+
- Add router in `routers/` directory
168+
- Register in `api.py` using `app.include_router()`
169+
170+
2. **New Service**:
171+
- Create service class in `services/`
172+
- Initialize in `ODAPIApplication.__init__()`
173+
- Add tests in `tests/test_<service_name>.py`
174+
175+
3. **New Integration**:
176+
- Create agent in `connectors/`
177+
- Register in `orchestrator.py`
178+
- Add required API keys to Secret Manager
179+
180+
4. **New Data Model**:
181+
- Create model in `firebase/models/`
182+
- Inherit from `FireStoreObject`
183+
- Implement required methods
184+
185+
## Key Features
186+
187+
### Authentication
188+
- Firebase ID token validation
189+
- Google OAuth 2.0 integration
190+
- User-specific encryption keys via Google Cloud KMS
191+
- Production-enforced security rules
192+
193+
### Real-time Communication
194+
- WebSocket support for streaming chat
195+
- Character-by-character response streaming
196+
- Tool call visualization
197+
- Voice interaction via Twilio WebRTC
198+
199+
### AI Integration
200+
- OpenAI gpt-4o with agents framework
201+
- Context-aware tool selection
202+
- Multi-agent orchestration
203+
- Automatic chat title generation
204+
205+
### Data Security
206+
- All sensitive tokens encrypted at rest
207+
- User-specific encryption keys
208+
- Secure OAuth state management
209+
- Comprehensive audit logging
210+
211+
## Security
212+
213+
### Best Practices
214+
- Never commit secrets or API keys
215+
- Use Google Secret Manager for production secrets
216+
- Enable 2FA on all service accounts
217+
- Regular security audits
218+
- Encrypted storage for all sensitive data
219+
220+
### Authentication Flow
221+
1. Client obtains Firebase ID token
222+
2. Token validated on each request
223+
3. User object loaded with permissions
224+
4. Request processed with user context
225+
65226
## Prerequisites
66227

67228
- Python 3.11+
@@ -233,133 +394,6 @@ gcloud app deploy prod.yaml --version=your-version-name
233394
- Higher resource allocation
234395
- Additional security measures
235396

236-
## Project Structure
237-
238-
```
239-
backend/
240-
├── api.py # Main FastAPI application entry point
241-
├── requirements.txt # Production dependencies
242-
├── test_requirements.txt # Testing dependencies
243-
├── app.yaml # Development deployment config
244-
├── prod.yaml # Production deployment config
245-
├── run_tests.py # Custom test runner
246-
├── CLAUDE.md # AI assistant guidance
247-
│
248-
├── routers/ # API route handlers
249-
│ ├── google.py # Google OAuth endpoints
250-
│ ├── plaid.py # Financial account linking
251-
│ ├── twilio/ # Voice call handling
252-
│ └── app_voice.py # In-app voice interactions
253-
│
254-
├── services/ # Business logic layer
255-
│ ├── auth_service.py # Authentication and authorization
256-
│ ├── chat_service.py # Chat management and AI integration
257-
│ └── location_service.py # Geolocation services
258-
│
259-
├── websocket/ # WebSocket implementation
260-
│ ├── connection_manager.py # Connection lifecycle
261-
│ └── websocket_handler.py # Chat interaction flow
262-
│
263-
├── firebase/ # Data models and persistence
264-
│ ├── models/ # Firestore document models
265-
│ │ ├── user.py # User profiles and settings
266-
│ │ ├── chat.py # Chat conversations
267-
│ │ ├── tokens.py # OAuth token storage
268-
│ │ └── ...
269-
│ └── firebase_init.py # Firebase initialization
270-
│
271-
├── connectors/ # Third-party integrations
272-
│ ├── orchestrator.py # Main AI agent orchestrator
273-
│ ├── voice_orchestrator.py # Voice-specific orchestrator
274-
│ ├── plaid_agent.py # Financial services
275-
│ ├── gmail_agent.py # Email integration
276-
│ └── ... # 30+ other integrations
277-
│
278-
└── tests/ # Test suite
279-
├── test_*.py # Test files mirror source structure
280-
└── conftest.py # pytest configuration
281-
```
282-
283-
## Code Organization
284-
285-
### Design Patterns
286-
287-
1. **Layered Architecture**: Clear separation between API, Service, Integration, and Data layers
288-
2. **Dependency Injection**: Services receive dependencies via constructors
289-
3. **Repository Pattern**: Firebase models abstract database operations
290-
4. **Agent-Based Architecture**: Specialized agents for different domains
291-
5. **Async/Await**: Consistent async patterns throughout
292-
293-
### Key Conventions
294-
295-
- **File Naming**: Snake_case for Python files (e.g., `auth_service.py`)
296-
- **Class Naming**: PascalCase for classes (e.g., `AuthService`)
297-
- **Function Naming**: Snake_case for functions (e.g., `validate_token()`)
298-
- **Test Files**: Prefix with `test_` (e.g., `test_auth_service.py`)
299-
- **Environment Variables**: UPPER_SNAKE_CASE (e.g., `OPENAI_API_KEY`)
300-
301-
### Adding New Features
302-
303-
1. **New API Endpoint**:
304-
- Add router in `routers/` directory
305-
- Register in `api.py` using `app.include_router()`
306-
307-
2. **New Service**:
308-
- Create service class in `services/`
309-
- Initialize in `ODAPIApplication.__init__()`
310-
- Add tests in `tests/test_<service_name>.py`
311-
312-
3. **New Integration**:
313-
- Create agent in `connectors/`
314-
- Register in `orchestrator.py`
315-
- Add required API keys to Secret Manager
316-
317-
4. **New Data Model**:
318-
- Create model in `firebase/models/`
319-
- Inherit from `FireStoreObject`
320-
- Implement required methods
321-
322-
## Key Features
323-
324-
### Authentication
325-
- Firebase ID token validation
326-
- Google OAuth 2.0 integration
327-
- User-specific encryption keys via Google Cloud KMS
328-
- Production-enforced security rules
329-
330-
### Real-time Communication
331-
- WebSocket support for streaming chat
332-
- Character-by-character response streaming
333-
- Tool call visualization
334-
- Voice interaction via Twilio WebRTC
335-
336-
### AI Integration
337-
- OpenAI gpt-4o with agents framework
338-
- Context-aware tool selection
339-
- Multi-agent orchestration
340-
- Automatic chat title generation
341-
342-
### Data Security
343-
- All sensitive tokens encrypted at rest
344-
- User-specific encryption keys
345-
- Secure OAuth state management
346-
- Comprehensive audit logging
347-
348-
## Security
349-
350-
### Best Practices
351-
- Never commit secrets or API keys
352-
- Use Google Secret Manager for production secrets
353-
- Enable 2FA on all service accounts
354-
- Regular security audits
355-
- Encrypted storage for all sensitive data
356-
357-
### Authentication Flow
358-
1. Client obtains Firebase ID token
359-
2. Token validated on each request
360-
3. User object loaded with permissions
361-
4. Request processed with user context
362-
363397
## Contributing
364398

365399
### Development Workflow

0 commit comments

Comments
 (0)