algerian-government-services

ameurb/algerian-government-services

3.1

If you are the rightful owner of algerian-government-services and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Algerian Government Services Chat Application is a ChatGPT-like intelligent assistant designed to facilitate access to Algerian government services, featuring automatic RTL/LTR support, MongoDB Atlas integration, and a streaming HTTP-MCP server.

๐Ÿ‡ฉ๐Ÿ‡ฟ Enhanced AI Government Services Assistant

An advanced AI-powered assistant for Algerian government services with real-time streaming, SQLite database, and multilingual support (Arabic, English, French).

Version License SQLite AI Streaming

๐ŸŒŸ Features

๐Ÿง  Advanced AI System

  • AI-powered query analysis with intent detection
  • Automatic language detection (Arabic, English, French)
  • Real-time streaming responses with markdown formatting
  • Human-like comprehensive guidance with step-by-step instructions

๐Ÿ—„๏ธ SQLite Database

  • Local file-based database for fast performance
  • Comprehensive government services data
  • Multilingual content with full translations
  • Advanced search indexing for accurate results

๐ŸŒŠ Real-time Streaming

  • Character-by-character streaming for instant responses
  • Professional markdown formatting in real-time
  • Enhanced user experience with typing indicators
  • Vercel AI SDK integration for optimal performance

๐ŸŒ Multilingual Support

  • Arabic (ุงู„ุนุฑุจูŠุฉ) - Primary language with RTL support
  • English - Administrative terminology and procedures
  • French (Franรงais) - Administrative French for legal context

๐Ÿš€ Quick Start

Prerequisites

  • Node.js 18+
  • OpenAI API key
  • TypeScript knowledge (optional)

Installation

# Clone repository
git clone https://github.com/ameurb/algerian-government-services.git
cd algerian-government-services

# Install dependencies  
npm install

# Configure environment
cp .env.example .env
# Add your OPENAI_API_KEY to .env

# Generate Prisma client and create database
npx prisma generate
npx prisma db push

# Seed database with government services
npx tsx prisma/sqlite-seed.ts

# Start development server
npm run dev

๐Ÿ“ก Streaming API Usage in Node.js

Basic Streaming Request

import fetch from 'node-fetch';

async function streamGovernmentServices(userQuery) {
  const response = await fetch('https://dzservices.findapply.com/api/enhanced-chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messages: [
        { role: 'user', content: userQuery }
      ],
      sessionId: `session_${Date.now()}`
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let accumulatedText = '';

  while (true) {
    const { done, value } = await reader.read();
    
    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    const lines = chunk.split('\\n').filter(line => line.trim());
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = line.slice(6);
        
        if (data === '[DONE]') {
          console.log('\\nโœ… Streaming completed!');
          console.log('\\n๐Ÿ“„ Full Response:');
          console.log(accumulatedText);
          return accumulatedText;
        }
        
        try {
          const parsed = JSON.parse(data);
          if (parsed.content) {
            accumulatedText += parsed.content;
            process.stdout.write(parsed.content); // Real-time display
          }
        } catch (parseError) {
          console.warn('Failed to parse:', data);
        }
      }
    }
  }
}

// Usage Examples
await streamGovernmentServices('ูƒูŠู ุฃุญุตู„ ุนู„ู‰ ุฌูˆุงุฒ ุงู„ุณูุฑุŸ');
await streamGovernmentServices('How to get a national ID?');
await streamGovernmentServices('Comment enregistrer une entreprise ?');

Advanced Streaming with Session Management

class AlgerianServicesClient {
  constructor(apiKey = null) {
    this.baseUrl = 'https://dzservices.findapply.com';
    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
    this.conversationHistory = [];
  }

  async streamChat(userMessage, onChunk = null, onComplete = null) {
    // Add user message to history
    this.conversationHistory.push({
      role: 'user',
      content: userMessage,
      timestamp: new Date()
    });

    const response = await fetch(`${this.baseUrl}/api/enhanced-chat`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        messages: this.conversationHistory,
        sessionId: this.sessionId
      })
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let fullResponse = '';

    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value, { stream: true });
        const lines = chunk.split('\\n').filter(line => line.trim());
        
        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);
            
            if (data === '[DONE]') {
              // Add assistant response to history
              this.conversationHistory.push({
                role: 'assistant',
                content: fullResponse,
                timestamp: new Date()
              });
              
              if (onComplete) onComplete(fullResponse);
              return fullResponse;
            }
            
            try {
              const parsed = JSON.parse(data);
              if (parsed.content) {
                fullResponse += parsed.content;
                if (onChunk) onChunk(parsed.content, fullResponse);
              }
            } catch (error) {
              console.warn('Parse error:', error);
            }
          }
        }
      }
    } finally {
      reader.releaseLock();
    }

    return fullResponse;
  }

  // Get conversation history
  getHistory() {
    return this.conversationHistory;
  }

  // Clear conversation
  clearHistory() {
    this.conversationHistory = [];
    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }
}

// Usage Example
const client = new AlgerianServicesClient();

// Stream with real-time callback
await client.streamChat(
  'ูƒูŠู ุฃุณุฌู„ ุดุฑูƒุฉ ุฌุฏูŠุฏุฉุŸ',
  (chunk, fullText) => {
    // Called for each streaming chunk
    console.log('๐Ÿ“ New chunk:', chunk);
  },
  (finalResponse) => {
    // Called when streaming completes
    console.log('โœ… Final response length:', finalResponse.length);
  }
);

// Continue conversation with context
await client.streamChat('ู…ุง ู‡ูŠ ุงู„ูˆุซุงุฆู‚ ุงู„ู…ุทู„ูˆุจุฉุŸ');

console.log('๐Ÿ“š Conversation history:', client.getHistory());

Express.js Integration

import express from 'express';
import { AlgerianServicesClient } from './algerian-services-client.js';

const app = express();
app.use(express.json());

const client = new AlgerianServicesClient();

// Streaming endpoint
app.post('/api/stream-chat', async (req, res) => {
  const { message, sessionId } = req.body;
  
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
    'Access-Control-Allow-Origin': '*'
  });

  try {
    await client.streamChat(
      message,
      (chunk) => {
        // Forward chunk to client
        res.write(`data: ${JSON.stringify({ content: chunk })}\\n\\n`);
      },
      (finalResponse) => {
        res.write('data: [DONE]\\n\\n');
        res.end();
      }
    );
  } catch (error) {
    res.write(`data: ${JSON.stringify({ error: error.message })}\\n\\n`);
    res.end();
  }
});

app.listen(3000, () => {
  console.log('๐Ÿš€ Server running on http://localhost:3000');
});

TypeScript Integration

interface StreamingResponse {
  content?: string;
  error?: string;
  metadata?: {
    tokensUsed?: number;
    servicesFound?: number;
    language?: string;
  };
}

interface ConversationMessage {
  role: 'user' | 'assistant';
  content: string;
  timestamp: Date;
}

class AlgerianServicesAPI {
  private baseUrl: string;
  private sessionId: string;
  private history: ConversationMessage[];

  constructor(baseUrl = 'https://dzservices.findapply.com') {
    this.baseUrl = baseUrl;
    this.sessionId = this.generateSessionId();
    this.history = [];
  }

  async *streamResponse(userQuery: string): AsyncIterable<string> {
    this.history.push({
      role: 'user',
      content: userQuery,
      timestamp: new Date()
    });

    const response = await fetch(`${this.baseUrl}/api/enhanced-chat`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        messages: this.history,
        sessionId: this.sessionId
      })
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    let accumulatedText = '';

    if (!reader) throw new Error('Response body not readable');

    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value, { stream: true });
        const lines = chunk.split('\\n').filter(line => line.trim());
        
        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);
            
            if (data === '[DONE]') {
              this.history.push({
                role: 'assistant',
                content: accumulatedText,
                timestamp: new Date()
              });
              return;
            }
            
            try {
              const parsed: StreamingResponse = JSON.parse(data);
              if (parsed.content) {
                accumulatedText += parsed.content;
                yield parsed.content;
              }
            } catch (error) {
              console.warn('Parse error:', error);
            }
          }
        }
      }
    } finally {
      reader.releaseLock();
    }
  }

  private generateSessionId(): string {
    return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }

  getConversationHistory(): ConversationMessage[] {
    return [...this.history];
  }
}

// TypeScript Usage
const api = new AlgerianServicesAPI();

console.log('๐Ÿค– Starting AI conversation...');
for await (const chunk of api.streamResponse('ูƒูŠู ุฃุญุตู„ ุนู„ู‰ ุฌูˆุงุฒ ุงู„ุณูุฑุŸ')) {
  process.stdout.write(chunk);
}

console.log('\\n๐Ÿ“š Conversation history:', api.getConversationHistory());

React.js Frontend Integration

import { useState, useEffect } from 'react';
import ReactMarkdown from 'react-markdown';

function useStreamingChat() {
  const [messages, setMessages] = useState([]);
  const [isStreaming, setIsStreaming] = useState(false);
  const [currentStream, setCurrentStream] = useState('');

  const streamMessage = async (userMessage: string) => {
    // Add user message
    setMessages(prev => [...prev, { role: 'user', content: userMessage }]);
    setIsStreaming(true);
    setCurrentStream('');

    try {
      const response = await fetch('/api/enhanced-chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          messages: [...messages, { role: 'user', content: userMessage }],
          sessionId: 'react_session'
        })
      });

      const reader = response.body?.getReader();
      const decoder = new TextDecoder();
      let accumulated = '';

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value, { stream: true });
        const lines = chunk.split('\\n');
        
        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);
            if (data === '[DONE]') {
              setMessages(prev => [...prev, { role: 'assistant', content: accumulated }]);
              setIsStreaming(false);
              setCurrentStream('');
              return;
            }
            
            try {
              const parsed = JSON.parse(data);
              if (parsed.content) {
                accumulated += parsed.content;
                setCurrentStream(accumulated);
              }
            } catch (error) {
              console.warn('Parse error:', error);
            }
          }
        }
      }
    } catch (error) {
      console.error('Streaming error:', error);
      setIsStreaming(false);
    }
  };

  return { messages, isStreaming, currentStream, streamMessage };
}

// React Component
export default function ChatInterface() {
  const { messages, isStreaming, currentStream, streamMessage } = useStreamingChat();

  return (
    <div className="chat-container">
      {messages.map((msg, i) => (
        <div key={i} className={`message ${msg.role}`}>
          <ReactMarkdown>{msg.content}</ReactMarkdown>
        </div>
      ))}
      
      {isStreaming && currentStream && (
        <div className="streaming-message">
          <ReactMarkdown>{currentStream}</ReactMarkdown>
          <span className="typing-cursor">|</span>
        </div>
      )}
      
      <ChatInput onSend={streamMessage} disabled={isStreaming} />
    </div>
  );
}

๐Ÿ—๏ธ Architecture

Frontend (React/Next.js)  โ†โ†’  Streaming API  โ†โ†’  AI Analysis  โ†โ†’  SQLite Database
     โ”‚                           โ”‚                    โ”‚                 โ”‚
   User Input              Enhanced Chat          OpenAI GPT-4     Government Services
   Markdown UI            /api/enhanced-chat      Query Analysis        Local DB
   Real-time UX           Streaming Response      Intent Detection      Fast Search

๐Ÿ”ง System Components:

  1. Frontend Application

    • Real-time streaming UI with markdown parsing
    • Multilingual interface (Arabic/English/French)
    • Professional government services styling

  2. AI-Powered Backend

    • Vercel AI SDK for advanced query processing
    • Automatic language detection and intent analysis
    • Comprehensive response generation with templates

  3. SQLite Database

    • Local government services database
    • Optimized for fast search and retrieval
    • Multilingual content with proper indexing

๐Ÿ“Š Available Services

Civil Status Services (ุงู„ุญุงู„ุฉ ุงู„ู…ุฏู†ูŠุฉ)

  • ๐Ÿ›‚ Passport Services (ุฎุฏู…ุงุช ุฌูˆุงุฒ ุงู„ุณูุฑ)

    • New passport application / ุทู„ุจ ุฌูˆุงุฒ ุณูุฑ ุฌุฏูŠุฏ
    • Passport renewal / ุชุฌุฏูŠุฏ ุฌูˆุงุฒ ุงู„ุณูุฑ
    • Passport tracking / ู…ุชุงุจุนุฉ ุทู„ุจ ุฌูˆุงุฒ ุงู„ุณูุฑ

  • ๐Ÿ†” Identity Documents (ูˆุซุงุฆู‚ ุงู„ู‡ูˆูŠุฉ)

    • National ID card / ุจุทุงู‚ุฉ ุงู„ุชุนุฑูŠู ุงู„ูˆุทู†ูŠุฉ
    • Birth certificates / ุดู‡ุงุฏุงุช ุงู„ู…ูŠู„ุงุฏ
    • Marriage certificates / ุดู‡ุงุฏุงุช ุงู„ุฒูˆุงุฌ

Business Services (ุฎุฏู…ุงุช ุงู„ุฃุนู…ุงู„)

  • ๐Ÿข Company Registration (ุชุณุฌูŠู„ ุงู„ุดุฑูƒุงุช)
  • ๐Ÿ“„ Commercial Licenses (ุงู„ุฑุฎุต ุงู„ุชุฌุงุฑูŠุฉ)
  • ๐Ÿ’ผ Trade Register (ุงู„ุณุฌู„ ุงู„ุชุฌุงุฑูŠ)

Education Services (ุฎุฏู…ุงุช ุงู„ุชุนู„ูŠู…)

  • ๐ŸŽ“ Higher Education Grants (ู…ู†ุญ ุงู„ุชุนู„ูŠู… ุงู„ุนุงู„ูŠ)
  • ๐Ÿ“š University Services (ุงู„ุฎุฏู…ุงุช ุงู„ุฌุงู…ุนูŠุฉ)

Transportation Services (ุฎุฏู…ุงุช ุงู„ู†ู‚ู„)

  • ๐Ÿš— Driving License (ุฑุฎุตุฉ ุงู„ุณูŠุงู‚ุฉ)
  • ๐Ÿš™ Vehicle Registration (ุชุณุฌูŠู„ ุงู„ู…ุฑูƒุจุงุช)

๐Ÿงช Testing the Streaming API

Simple Test Script

# Test with Arabic query
curl -X POST https://dzservices.findapply.com/api/enhanced-chat \\
  -H "Content-Type: application/json" \\
  -d '{
    "messages": [{"role": "user", "content": "ูƒูŠู ุฃุญุตู„ ุนู„ู‰ ุฌูˆุงุฒ ุงู„ุณูุฑุŸ"}],
    "sessionId": "test_session"
  }'

# Test with English query  
curl -X POST https://dzservices.findapply.com/api/enhanced-chat \\
  -H "Content-Type: application/json" \\
  -d '{
    "messages": [{"role": "user", "content": "How to get a passport?"}],
    "sessionId": "test_session"
  }'

# Test with French query
curl -X POST https://dzservices.findapply.com/api/enhanced-chat \\
  -H "Content-Type: application/json" \\
  -d '{
    "messages": [{"role": "user", "content": "Comment obtenir un passeport ?"}],
    "sessionId": "test_session"
  }'

Expected Response Format

data: {"content":"#"}
data: {"content":" ๐ŸŽฏ"}  
data: {"content":" Direct"}
data: {"content":" Answer"}
data: {"content":"\\n\\n"}
data: {"content":"To"}
data: {"content":" apply"}
data: {"content":" for"}
data: {"content":" an"}
data: {"content":" Algerian"}
data: {"content":" passport"}
data: {"content":"..."}
data: [DONE]

๐ŸŒ Production Deployment

The application is deployed and available at:

Features in Production:

  • โœ… Real-time AI streaming with markdown formatting
  • โœ… SQLite database with comprehensive government services
  • โœ… Multilingual support with automatic language detection
  • โœ… Professional UI with enhanced user experience
  • โœ… Error handling and graceful fallbacks

๐Ÿ“ž API Support

Error Handling

The API returns structured errors:

{
  "error": "Internal server error",
  "message": "Specific error description",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Rate Limiting

  • Production: 60 requests per minute per IP
  • Development: No limits

Response Times

  • Average: 2-8 seconds for complete response
  • Streaming: Immediate start, character-by-character delivery
  • Database: < 100ms query response time

๐Ÿค Contributing

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

๐Ÿ“„ License

This project is licensed under the MIT License - see the file for details.

๐ŸŽ‰ Built with โค๏ธ for the Algerian community ๐Ÿ‡ฉ๐Ÿ‡ฟ

Empowering citizens with intelligent AI-powered access to government services through advanced streaming technology.