# ADL System - Project Structure
```
ADL/
├── backend/ # GraphQL Backend Server
│ ├── database.js # SQLite database operations
│ ├── graphql-server.js # Apollo Server setup
│ ├── resolvers.js # GraphQL resolvers
│ └── schema.js # GraphQL schema definitions
│
├── mcp-server/ # Model Context Protocol Server
│ ├── graphql-client.js # GraphQL client for MCP
│ ├── server.js # MCP server implementation
│ └── package.json # MCP server dependencies
│
├── ui/ # Web User Interface
│ ├── index.html # Single-page application
│ ├── server.js # Express server for UI
│ └── package.json # UI server dependencies
│
├── scripts/ # Utility Scripts
│ ├── start-all.js # Start all services
│ └── load-sample-data.js # Load sample ADL entries
│
├── data/ # Database Storage
│ └── adl.sqlite # SQLite database (created at runtime)
│
├── docs/ # Documentation
│ ├── README.md # Main documentation
│ ├── INSTALL-LINUX.md # Linux installation guide
│ ├── MCP-SETUP.md # MCP configuration guide
│ ├── GRAPHQL-EXAMPLES.md # GraphQL query examples
│ └── TESTING.md # Testing guide
│
├── package.json # Root package configuration
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Docker image definition
├── .gitignore # Git ignore patterns
├── .env.example # Example environment variables
├── sample-data.json # Sample ADL entries
├── start.sh # Linux startup script
└── stop.sh # Linux stop script
```
## Component Overview
### Backend (GraphQL Server)
- **Technology**: Node.js, Apollo Server, GraphQL
- **Database**: SQLite with better-sqlite3
- **Port**: 4000 (configurable via GRAPHQL_PORT)
- **Features**:
- CRUD operations for ADL entries
- Type-safe GraphQL schema
- Persistent storage with SQLite
- Auto-generated timestamps
### MCP Server
- **Technology**: Model Context Protocol SDK
- **Communication**: stdio (standard input/output)
- **Integration**: Connects to GraphQL backend
- **Tools Exposed**:
- adl_list: List all entries
- adl_get: Get entry by ID
- adl_create: Create new entry
- adl_update: Update existing entry
- adl_delete: Delete entry
### UI Application
- **Technology**: HTML, CSS, JavaScript (Vanilla)
- **Server**: Express.js
- **Port**: 3000 (configurable via UI_PORT)
- **Features**:
- Table view of all ADL entries
- Create/Edit/Delete operations
- Fact sheets management
- Status filtering (Proposed/Approved)
- Responsive design
## Data Model
### ADL Entry Schema
```typescript
interface ADLEntry {
id: string; // UUID, auto-generated
created: string; // ISO 8601 timestamp
lastEdited: string; // ISO 8601 timestamp
author: string; // Author name
title: string; // Decision title
decision: string; // Detailed description
factSheets: string[]; // SAP/LeanIX fact sheet names
status: 'Proposed' | 'Approved';
}
```
## Technology Stack
### Runtime
- Node.js 18+
- ES Modules (type: "module")
### Backend Dependencies
- @apollo/server: GraphQL server
- graphql: GraphQL implementation
- better-sqlite3: SQLite database
- uuid: UUID generation
### MCP Dependencies
- @modelcontextprotocol/sdk: MCP protocol implementation
- node-fetch: HTTP client for GraphQL
### UI Dependencies
- express: Web server
- No frontend framework (Vanilla JS)
### DevOps
- Docker & Docker Compose
- Linux shell scripts
- Systemd service support
## Deployment Options
### 1. Local Development
```bash
npm install
npm start
```
### 2. Docker
```bash
docker-compose up -d
```
### 3. Linux Service
```bash
sudo systemctl enable adl
sudo systemctl start adl
```
## Port Configuration
| Service | Default Port | Environment Variable |
|----------|-------------|---------------------|
| GraphQL | 4000 | GRAPHQL_PORT |
| UI | 3000 | UI_PORT |
| MCP | stdio | N/A |
## Data Persistence
- **Storage**: SQLite database at `data/adl.sqlite`
- **Schema**: Automatically created on first run
- **Backup**: Copy `data/adl.sqlite` file
- **Reset**: Delete `data/adl.sqlite` to start fresh
## API Integration Points
### 1. GraphQL API
- **Endpoint**: http://localhost:4000/graphql
- **Protocol**: HTTP POST with JSON
- **Playground**: Available in browser
### 2. MCP Interface
- **Protocol**: stdio (JSON-RPC)
- **Client**: Any MCP-compatible client
- **Use Case**: AI assistant integration
### 3. Web UI
- **Access**: http://localhost:3000
- **API**: Calls GraphQL directly from browser
- **CORS**: Enabled for development
## Development Workflow
1. **Start GraphQL server**: `npm run start:graphql`
2. **Start UI server**: `npm run start:ui`
3. **Make changes**: Edit files in respective directories
4. **Test**: Use GraphQL Playground or Web UI
5. **Load sample data**: `npm run load-sample-data`
## Security Considerations
### Current Implementation
- SQL injection: Protected by prepared statements
- Input validation: GraphQL schema validation
- CORS: Enabled for all origins (development)
### Production Recommendations
- Enable HTTPS
- Configure CORS whitelist
- Add authentication/authorization
- Rate limiting on GraphQL endpoint
- Input sanitization for fact sheets
- Database encryption at rest
## Performance Characteristics
### GraphQL Server
- Single-threaded Node.js
- Synchronous SQLite operations
- Suitable for: Small to medium workloads
- Horizontal scaling: Not directly supported
### Database
- SQLite: Embedded database
- Concurrent reads: Supported
- Concurrent writes: Limited
- Max database size: 281 TB (practical limit much lower)
### UI Server
- Static file serving
- Minimal server-side logic
- Cacheable assets
## Extension Points
### Adding New Fields
1. Update GraphQL schema in `backend/schema.js`
2. Update resolvers in `backend/resolvers.js`
3. Modify database operations in `backend/database.js`
4. Update UI in `ui/index.html`
5. Update MCP tools in `mcp-server/server.js`
### Adding Authentication
1. Add user table to database
2. Implement JWT token generation
3. Add authentication middleware to GraphQL
4. Update UI with login form
5. Pass tokens in GraphQL requests
### Adding Search/Filtering
1. Add filter parameters to GraphQL queries
2. Implement SQL WHERE clauses in database.js
3. Add search UI elements
4. Update MCP tools with filter support
## Testing Strategy
### Unit Testing
- Database operations (CRUD)
- GraphQL resolvers
- MCP tool handlers
### Integration Testing
- GraphQL API endpoints
- MCP server communication
- UI → GraphQL → Database flow
### E2E Testing
- Full user workflows
- Cross-browser compatibility
- Mobile responsiveness
## Monitoring & Observability
### Logs
- Console output for all services
- Systemd journal (when running as service)
- Docker logs (when containerized)
### Metrics (Future Enhancement)
- Request count and latency
- Database query performance
- Error rates
- Active connections
## Known Limitations
1. **SQLite Concurrency**: Limited write concurrency
2. **No Authentication**: Open access to all operations
3. **No Search**: Must filter client-side
4. **No Pagination**: All entries loaded at once
5. **No Validation**: Minimal input validation beyond schema
6. **No Audit Trail**: Changes not tracked
7. **No Webhooks**: No event notifications
## Future Enhancements
- [ ] User authentication and authorization
- [ ] Full-text search across entries
- [ ] Pagination for large datasets
- [ ] Audit trail for changes
- [ ] Email notifications
- [ ] Integration with external systems (Jira, Confluence)
- [ ] Advanced filtering and sorting
- [ ] Export to PDF/Markdown
- [ ] Version history for entries
- [ ] Comments and discussions
- [ ] File attachments
- [ ] Tags/categories beyond fact sheets
## Support & Maintenance
### Backup Procedures
```bash
# Backup database
cp data/adl.sqlite backups/adl-$(date +%Y%m%d).sqlite
# Restore database
cp backups/adl-20260122.sqlite data/adl.sqlite
```
### Log Rotation
```bash
# If using systemd
sudo journalctl --vacuum-time=7d --unit=adl
```
### Updates
```bash
# Update dependencies
npm update
# Test updates
npm run start:graphql
npm run start:ui
```
## License
MIT License - See LICENSE file for details
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit pull request
5. Follow code style guidelines
## Contact
- **Author**: dk123579@gmail.com
- **Repository**: github.com/dk123579/ADL
- **Issues**: Use GitHub Issues for bug reports
