\documentclass[11pt,a4paper]{article}
\usepackage[margin=1in]{geometry}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{array}
\usepackage{float}
\usepackage{enumitem}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{tikz}
\usetikzlibrary{arrows.meta,positioning,shapes.geometric,fit,calc}

\hypersetup{
  colorlinks=true,
  linkcolor=blue,
  urlcolor=blue
}

\setlist[itemize]{leftmargin=18pt}
\setlist[enumerate]{leftmargin=20pt}

\newcommand{\safeimage}[2]{%
  \IfFileExists{#1}{\includegraphics[width=#2]{#1}}{\fbox{Missing image: #1}}%
}

\title{CivicConnect: Complete Working Documentation}
\author{Generated from repository implementation}
\date{March 31, 2026}

\begin{document}
\maketitle
\tableofcontents
\newpage

\section{Document Scope}
This document describes the full implementation flow of CivicConnect from source code and infrastructure files in the workspace. It covers:
\begin{itemize}
  \item system architecture and inter-service communication,
  \item admin panel and citizen Flutter app behavior,
  \item backend microservices, data stores, and async pipelines,
  \item RAG chatbot workflow,
  \item Kubernetes management/deployment model,
  \item core entity-relationship model,
  \item screenshot walkthroughs (admin web and mobile-form-factor Flutter flow).
\end{itemize}

\section{Repository Architecture Summary}
CivicConnect is built as a microservices platform with two primary user surfaces:
\begin{itemize}
  \item Government management interface: Vue 3 admin panel.
  \item Citizen interface: Flutter application with multiple feature modules.
\end{itemize}

Gateway and service topology are centered around NGINX reverse proxying to domain services.

\subsection{Primary Service Matrix}
\begin{longtable}{>{\raggedright\arraybackslash}p{3.1cm} >{\raggedright\arraybackslash}p{3.5cm} >{\raggedright\arraybackslash}p{2cm} >{\raggedright\arraybackslash}p{5.2cm}}
\toprule
Service & Stack & Port & Responsibility \\
\midrule
admin-service & Go + Gin + GORM & 8081 & Authentication, admin hierarchy, governments, departments, follows, admin dashboard aggregates \\
content-service & Node.js + Express + pg & 8082 (HTTP), 50051 (gRPC) & Posts, articles, comments, likes/bookmarks, media upload, AI summary trigger \\
complaint-service & Go + Gin + GORM + PostGIS & 8083 & Complaint lifecycle, votes, actions, nearby geo queries, complaint media \\
chatbot-service & Python FastAPI + WebSocket & 8084 & PulseBot chat API/WS, RAG retrieval, vector ingest/update \\
ai-worker & Python + RabbitMQ + gRPC & 8085, 50052 & Async summarization and complaint analysis consumers, assistant/chat worker duties \\
admin-panel & Vue 3 + Vite & 3000 dev / 80 runtime & Government operations UI \\
\bottomrule
\end{longtable}

\subsection{Core Infra Components}
\begin{itemize}
  \item PostgreSQL with multiple logical databases: \texttt{admin\_db}, \texttt{content\_db}, \texttt{complaint\_db}.
  \item PostGIS enabled in \texttt{complaint\_db} for geospatial queries.
  \item RabbitMQ for async job messaging.
  \item Redis for cache/session/counters/chat history.
  \item MinIO for object storage (post/complaint uploads).
  \item ChromaDB as vector store for RAG retrieval.
\end{itemize}

\section{End-to-End Request Flow}
\subsection{Gateway Routes}
NGINX routes client traffic by prefix:
\begin{itemize}
  \item \texttt{/api/v1/auth/*} and \texttt{/api/v1/admin/*} $\rightarrow$ admin-service
  \item \texttt{/api/v1/content/*} $\rightarrow$ content-service
  \item \texttt{/api/v1/complaints*} $\rightarrow$ complaint-service
  \item \texttt{/api/v1/chatbot/*} and \texttt{/ws/*} $\rightarrow$ chatbot-service
  \item \texttt{/uploads/*} proxied to MinIO
\end{itemize}

\subsection{Control and Data Planes}
\begin{enumerate}
  \item User interfaces call gateway HTTP APIs.
  \item Services persist domain state in service-owned tables/databases.
  \item Event-producing actions publish to RabbitMQ queues.
  \item AI worker consumes queues and sends back summaries/analysis via gRPC or downstream updates.
  \item Chatbot service ingests knowledge documents into ChromaDB and serves contextual responses.
\end{enumerate}

\section{Vector Architecture Diagram}
\begin{figure}[H]
\centering
\begin{tikzpicture}[
  node distance=10mm and 11mm,
  box/.style={draw, rounded corners=2pt, fill=blue!5, minimum width=29mm, minimum height=9mm, align=center, font=\small},
  infra/.style={draw, rounded corners=2pt, fill=green!8, minimum width=28mm, minimum height=9mm, align=center, font=\small},
  arr/.style={-Latex, thick}
]

\node[box] (citizen) {Citizen App\\Flutter};
\node[box, right=of citizen] (nginx) {NGINX\\Gateway};
\node[box, right=of nginx] (admin) {admin-service\\Go/Gin};
\node[box, below=of admin] (content) {content-service\\Node/Express};
\node[box, below=of content] (complaint) {complaint-service\\Go/PostGIS};
\node[box, below=of complaint] (chatbot) {chatbot-service\\FastAPI + WS};
\node[box, below=of nginx] (panel) {Admin Panel\\Vue 3};
\node[box, right=of content] (aiw) {ai-worker\\Python};

\node[infra, right=of admin] (pg1) {PostgreSQL\\admin\_db};
\node[infra, right=of content] (pg2) {PostgreSQL\\content\_db};
\node[infra, right=of complaint] (pg3) {PostgreSQL\\complaint\_db + PostGIS};
\node[infra, below=of aiw] (rabbit) {RabbitMQ};
\node[infra, below=of rabbit] (redis) {Redis};
\node[infra, below=of redis] (minio) {MinIO};
\node[infra, left=of minio] (chroma) {ChromaDB};

\draw[arr] (citizen) -- node[above, font=\scriptsize]{REST} (nginx);
\draw[arr] (panel) -- (nginx);
\draw[arr] (nginx) -- (admin);
\draw[arr] (nginx) -- (content);
\draw[arr] (nginx) -- (complaint);
\draw[arr] (nginx) -- (chatbot);

\draw[arr] (admin) -- (pg1);
\draw[arr] (content) -- (pg2);
\draw[arr] (complaint) -- (pg3);

\draw[arr] (content) -- node[above, font=\scriptsize]{publish} (rabbit);
\draw[arr] (complaint) -- node[above, font=\scriptsize]{publish} (rabbit);
\draw[arr] (rabbit) -- node[right, font=\scriptsize]{consume} (aiw);
\draw[arr] (content) -- node[above, font=\scriptsize]{gRPC} (aiw);

\draw[arr] (admin) -- (redis);
\draw[arr] (content) -- (redis);
\draw[arr] (complaint) -- (redis);
\draw[arr] (chatbot) -- (redis);
\draw[arr] (aiw) -- (redis);

\draw[arr] (content) -- (minio);
\draw[arr] (complaint) -- (minio);
\draw[arr] (chatbot) -- (chroma);

\end{tikzpicture}
\caption{CivicConnect runtime architecture (vector diagram generated in LaTeX).}
\end{figure}

\section{Management Portal Working (Vue Admin Panel)}
\subsection{Auth and Role Model}
The admin panel uses Pinia state with token/user persisted in browser storage. Route guards enforce role-scoped access:
\begin{itemize}
  \item \texttt{super\_admin}: municipalities and manager administration.
  \item \texttt{manager}: complaints, departments, dept manager setup, articles.
  \item \texttt{dept\_manager}: operational complaint/article/community actions within department scope.
\end{itemize}

\subsection{Operational Screens}
\begin{itemize}
  \item Dashboard: complaint counters, quick actions, recent complaint feed.
  \item Complaints: status transitions, action timeline, reassignment for category correction.
  \item Articles: create/edit announcements, category filtering, AI summary visibility.
  \item Community Posts: official responses to citizen posts and comment auditing.
  \item Departments, Admins, Municipalities: hierarchical entity management.
  \item Users: searchable citizen registry with pagination and sort.
\end{itemize}

\section{Citizen App Working (Flutter)}
Flutter uses \texttt{go\_router} and feature modules for Home, Articles, Posts, Complaints, Communities, Chatbot Assistant, and Profile.

\subsection{Route and Navigation Pattern}
\begin{itemize}
  \item Top-level auth routes: login/register.
  \item Full-screen detail routes: article, post, complaint, assistant, government detail.
  \item Indexed shell route for bottom navigation tabs.
\end{itemize}

\subsection{Client Service Layer}
The app calls gateway endpoints through dedicated service classes:
\begin{itemize}
  \item Auth service for citizen login/register/session restore.
  \item Content service for articles/posts/comment interactions.
  \item Complaint service for complaint CRUD and progress states.
  \item Government service for follow/discovery flows.
  \item Chatbot service for REST and WebSocket conversations.
\end{itemize}

\section{Backend Services: Working Details}
\subsection{admin-service (Go)}
\begin{itemize}
  \item Citizen auth: register/login/profile/password/session verification.
  \item Admin auth: admin login, role-based middleware, dashboard metrics.
  \item Government structure: municipalities, departments, officials, admins.
  \item Follow graph: user-official and user-government follow tables.
\end{itemize}

\subsection{content-service (Node.js)}
\begin{itemize}
  \item Tables include posts, comments, likes, bookmarks, multimedia, and articles.
  \item Supports media upload via MinIO and article management with optional AI summaries.
  \item Pushes content events to chatbot ingest endpoint for near real-time RAG refresh.
  \item Exposes gRPC endpoint used by AI worker for enrichment tasks.
\end{itemize}

\subsection{complaint-service (Go + PostGIS)}
\begin{itemize}
  \item Complaint lifecycle with status transitions and completion percentages.
  \item Complaint comments, action history, image uploads.
  \item Nearby complaints query using geospatial functions in PostGIS.
  \item Publishes complaint analysis events for asynchronous AI processing.
\end{itemize}

\subsection{ai-worker (Python)}
\begin{itemize}
  \item Consumes \texttt{ai\_summarize} and \texttt{complaint\_analysis} queues from RabbitMQ.
  \item Provides gRPC-driven AI tasks and stores thread context in Redis.
  \item Uses Groq/Gemini strategy with fallback behavior.
\end{itemize}

\subsection{chatbot-service (FastAPI + RAG)}
\begin{itemize}
  \item REST endpoint \texttt{/ask} and WebSocket endpoint \texttt{/ws/{client\_id}}.
  \item Ingests policy JSON corpus and dynamic content from articles/posts/complaints.
  \item Stores embeddings in ChromaDB and filters retrieval using metadata (government/department/category).
  \item Maintains chat history in Redis and exports Prometheus metrics.
\end{itemize}

\section{RAG Chatbot Workflow}
\subsection{Ingestion Pipeline}
\begin{enumerate}
  \item Startup: policy corpora are ingested into ChromaDB as baseline knowledge.
  \item Dynamic refresh: service fetches content and complaint data periodically.
  \item Event sync: content-service can call \texttt{/ingest/event} so newly created/updated content becomes searchable quickly.
\end{enumerate}

\subsection{Query Pipeline}
\begin{enumerate}
  \item User message arrives with optional government context.
  \item Relevant vectors retrieved from ChromaDB by semantic similarity + metadata filters.
  \item Prompt assembled with conversation context and retrieved snippets.
  \item LLM response generated using Groq or Gemini (with fallback templates).
  \item Reply and history persisted in Redis.
\end{enumerate}

\section{Kubernetes Management Flow}
Kubernetes manifests under \texttt{infrastructure/k8s} define namespace-scoped deployment for all services and infra.

\subsection{Deployment Design}
\begin{itemize}
  \item Namespace: \texttt{civic-connect}.
  \item Workloads: Deployments for services, StatefulSet for PostgreSQL.
  \item Config and secrets: centralized via ConfigMaps and Secret refs.
  \item Access: ingress + optional NodePorts for local development.
  \item Health: readiness/liveness probes on service health endpoints.
\end{itemize}

\subsection{Operational Lifecycle}
\begin{enumerate}
  \item Build images with Skaffold profile.
  \item Apply namespace, secrets/config, stateful infra, then app services.
  \item Validate probes and ingress routing.
  \item Monitor logs and metrics from chatbot and service health endpoints.
\end{enumerate}

\section{ER Diagram and Data Model}
\begin{figure}[H]
\centering
\begin{tikzpicture}[
  entity/.style={draw, rounded corners=2pt, fill=orange!8, minimum width=28mm, minimum height=8mm, align=center, font=\small},
  rel/.style={-Latex, thick},
  node distance=9mm and 10mm
]

\node[entity] (user) {user};
\node[entity, right=of user] (gov) {local\_government};
\node[entity, right=of gov] (dept) {department};
\node[entity, below=of user] (post) {post};
\node[entity, right=of post] (comment) {comment};
\node[entity, below=of post] (complaint) {complaint};
\node[entity, right=of complaint] (action) {complaint\_action};
\node[entity, below=of user] at ($(user)!0.5!(complaint)$) (admin) {government\_admin};
\node[entity, below=of gov] (article) {article};
\node[entity, below=of dept] (follows) {government\_follow / follower};

\draw[rel] (user) -- node[above, font=\scriptsize]{files} (complaint);
\draw[rel] (user) -- node[left, font=\scriptsize]{creates} (post);
\draw[rel] (user) -- node[above, font=\scriptsize]{writes} (comment);
\draw[rel] (gov) -- node[above, font=\scriptsize]{has} (dept);
\draw[rel] (gov) -- node[left, font=\scriptsize]{publishes} (article);
\draw[rel] (dept) -- node[right, font=\scriptsize]{handles} (complaint);
\draw[rel] (complaint) -- node[above, font=\scriptsize]{timeline} (action);
\draw[rel] (admin) -- node[above, font=\scriptsize]{manages} (dept);
\draw[rel] (admin) -- node[left, font=\scriptsize]{authors} (article);
\draw[rel] (comment) -- node[above, font=\scriptsize]{belongs to} (post);
\draw[rel] (user) -- node[above, font=\scriptsize]{follows} (follows);
\draw[rel] (gov) -- node[right, font=\scriptsize]{followed by} (follows);

\end{tikzpicture}
\caption{Core ER view across admin/content/complaint domains.}
\end{figure}

\subsection{Schema Notes}
\begin{itemize}
  \item Databases are service-scoped; cross-service joins are avoided at runtime.
  \item Relationships are maintained through IDs and enforced in service logic.
  \item Full-text vectors are used in article search.
  \item Geospatial fields and functions are used in complaint discovery by proximity.
\end{itemize}

\section{YouTube API Integration Status}
YouTube API integration is \textbf{not implemented} in the current CivicConnect codebase. This section is intentionally retained only as implementation status clarification:
\begin{itemize}
  \item no runtime routes/services call YouTube Data API,
  \item no YouTube ingestion or playback business flow is wired in backend services,
  \item documentation focus remains on the implemented CivicConnect modules.
\end{itemize}

\section{Screenshot Walkthrough}
\subsection{Admin Panel Screens}
\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/01-login.png}{0.96\textwidth}
\caption{Admin panel login screen.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/02-dashboard-manager.png}{0.96\textwidth}
\caption{Manager dashboard with complaint metrics and quick actions.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/03-complaints-manager.png}{0.96\textwidth}
\caption{Complaints operations view with status and action handling.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/04-articles-manager.png}{0.96\textwidth}
\caption{Articles and announcements management.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/05-community-posts.png}{0.96\textwidth}
\caption{Community posts moderation with official response flow.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/06-departments-manager.png}{0.96\textwidth}
\caption{Department management for municipality managers.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/07-citizens-manager.png}{0.96\textwidth}
\caption{Citizen listing with search and pagination.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/08-settings-manager.png}{0.96\textwidth}
\caption{Settings view: account and municipality details.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/09-municipalities-superadmin.png}{0.96\textwidth}
\caption{Super admin municipality management.}
\end{figure}

\begin{figure}[H]
\centering
\safeimage{../screenshots/admin-panel/10-admins-superadmin.png}{0.96\textwidth}
\caption{Super admin manager administration table.}
\end{figure}

\subsection{Flutter Mobile-Form-Factor Screens (390x844)}
\begin{figure}[H]
\centering
\safeimage{../screenshots/flutter-mobile/00-mobile-flow-overview.png}{0.96\textwidth}
\caption{Mobile flow overview generated at phone form factor.}
\end{figure}

\begin{figure}[H]
\centering
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/01-home-screen.png}{\textwidth}\\[2mm]
\small Home
\end{minipage}
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/02-articles-screen.png}{\textwidth}\\[2mm]
\small Articles
\end{minipage}
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/03-posts-screen.png}{\textwidth}\\[2mm]
\small Posts
\end{minipage}
\caption{Mobile screens group A.}
\end{figure}

\begin{figure}[H]
\centering
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/04-complaints-screen.png}{\textwidth}\\[2mm]
\small Complaints
\end{minipage}
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/05-chatbot-screen.png}{\textwidth}\\[2mm]
\small PulseBot
\end{minipage}
\begin{minipage}{0.32\textwidth}\centering
\safeimage{../screenshots/flutter-mobile/06-profile-screen.png}{\textwidth}\\[2mm]
\small Profile
\end{minipage}
\caption{Mobile screens group B.}
\end{figure}

\section{Build and Operations Commands}
\subsection{Docker Compose}
\begin{verbatim}
cd civic-connect/infrastructure/docker
docker compose up --build -d
\end{verbatim}

\subsection{Kubernetes + Skaffold}
\begin{verbatim}
minikube start
minikube addons enable ingress
kubectl apply -f civic-connect/infrastructure/k8s/
skaffold dev --port-forward
\end{verbatim}

\subsection{Service Health Validation}
\begin{itemize}
  \item Admin: \texttt{/health}
  \item Content: \texttt{/health}
  \item Complaint: \texttt{/health}
  \item Chatbot: \texttt{/health}, \texttt{/metrics}
\end{itemize}

\section{Closing Notes}
The platform is production-oriented in architecture (service isolation, async processing, infra probes, ingress control) and supports both governance workflows and citizen-facing engagement with AI-assisted support. This document package can be extended with release-specific API appendices and deployment runbooks per environment.

\end{document}
