Operating & improving · Personal project
ssu Campus AI Platform
ssuAI, ssuMCP, ssuAgent, and ssu-ai-service connect Soongsil University data to the web, natural-language agents, and standard MCP tools in an operating platform.
Current status The web app, chat, MCP, and embedding services are in operation and continue to improve as I monitor changes in external university systems and the constraints of a single-node cluster.
Verified scope
Contribution boundaries and evidence
- Direct role
- Designed, implemented, and operate 4 services
- Team boundary
- Independently led project
- Evidence visibility
- Public repositories and evidence
- Contribution evidence
- Design, implementation, operation, and cross-service contracts across four services
- Repository-level ADRs, work logs, troubleshooting records, and deployment verification
System architecture
Service architecture
These repository-source diagrams show the service boundaries and operating flows. Select an image to open it at full size.
Product screens
Key operating screens
These screens show the service's primary features and operating state. Select an image to open it at full size.
Problem
General-purpose AI cannot directly work with university dining menus, announcements, library data, academic calendars, or a student’s timetable, grades, and LMS assignments. Instead of copying university data into a chatbot’s knowledge base, I built a tool layer that lets the web application and external MCP clients use the same service capabilities.
Design
- The Spring Boot service shares the same business logic between its REST API and MCP tools.
- Next.js provides the web dashboard and same-origin BFF.
- The LangGraph agent routes requests by domain and streams tool execution over SSE.
- Write operations follow a
prepare → confirmflow that requires explicit user approval.
The four services have distinct responsibilities. ssuAI owns the user-facing web application and same-origin BFF. ssuMCP collects university data and exposes 52 MCP tools. ssuAgent handles LangGraph routing and HITL flows. ssu-ai-service isolates embedding requests behind a separate FastAPI gateway. Service contracts form the boundary so that neither the frontend nor the agent needs to know the implementation details of university systems.
One codebase for desktop and mobile
ssuAI is one responsive Next.js web application rather than a separate native app. AppShell uses a fixed 246px sidebar on wide screens and switches to a top bar plus five bottom tabs on smaller screens. The bottom navigation respects the device safe area so it does not overlap the home indicator.
Data fetching and authentication state stay in the same component tree; only presentation changes with available width. Home widgets move from three desktop columns to one mobile column, while the weekly timetable changes from a five-day grid to a today-first list. Chat uses dvh to fill the remaining viewport, and mobile inputs stay at 16px to avoid iOS focus zoom without disabling pinch zoom.
Reliability and safety boundaries
External systems such as the university portal, library, and LMS can change their response formats and authentication state. I use provider fallback, timeouts, circuit breakers, and caching, while keeping error contracts separate so that failures are not returned as normal data. User-specific data and write tools verify thread, session, and principal ownership. Operations such as seat reservations prepare an intent and request confirmation again before execution.
The embedding service fails closed when its API key is missing or its upstream fails, and it does not reflect upstream error bodies back to users. The focus is not simply connecting an LLM to a chatbot, but turning authentication, tool execution, and state transitions into operable contracts.
Operations
I run k3s, Helm, ArgoCD, Traefik, and cert-manager on a single Oracle ARM64 node. The platform uses PostgreSQL, Redis, and Kafka, with Prometheus/Grafana, Tempo, and Loki connecting metrics, traces, and logs. I documented GitOps drift, image architecture mismatches, and Kafka and Tempo resource failures as real incident records.
A successful CI run is not treated as a completed deployment. I verify the GHCR multi-architecture manifest, ArgoCD reconciliation, the actual Pod digest, health, and a user request in sequence. Metrics, traces, and logs are connected across the same request, and I observe container startup time within the constraints of ARM64 images and limited resources.
Verified results
I verified real responses from the public web, chat, MCP, embedding health, and Grafana paths. ssuMCP retains records of full test-suite runs at different points in time, real-account E2E verification, and single-flight validation for concurrent requests to reserve the same seat. Because the total number of tests keeps changing, this page does not freeze an aggregate number without a reproducible source link.
Limitations
The single-node deployment is not a highly available cluster that can survive a node failure. The point of the project is not to exaggerate its scale, but to make deployment, observability, and recovery paths explainable even within a constrained environment.
The platform is also affected by policy and quota changes in external university systems and free LLM providers. NetworkPolicy remains deferred after evaluating the current CNI and external FQDN constraints. I document these constraints as current operating boundaries and conditions for the next improvement rather than hiding them.