InStadium Web is the browser-first experience of the InStadium ecosystem, built for discovery of Indian sports venues, athlete storytelling, and editorial content with integrated operational tools.
This README is intentionally architecture-first and flow-first. It provides complete high-level documentation with professional system views, while reserving focused space for deeper technical references to be added later.
- Showcases stadiums, sports, and player narratives through public pages
- Supports QR-based stadium entry paths and deep-linked experiences
- Offers discovery, QR, and assistant workflows for content-rich experiences
- Exposes server routes for data retrieval, chat, and administrative processes
- Fans and visitors exploring venues and sports
- Content and editorial contributors
- Admin users managing platform operations and curated content context
This context diagram shows InStadium Web as part of a larger digital ecosystem. It highlights external users, backend services, and infrastructure dependencies. Use this as the first architecture view before drilling into components.
flowchart TB
users[Public Users]
admin[Admin and Ops Users]
web[InStadium Web\nNext.js App Router]
api[App Route APIs]
db[(Neon Postgres)]
prisma[Prisma ORM]
cloud[Cloudinary Media]
ai[OpenAI Chat Service]
users --> web
admin --> web
web --> api
api --> prisma
prisma --> db
api --> cloud
api --> ai
This container view separates UI rendering, route handlers, and data/integration layers. It clarifies responsibility boundaries for front-end, application API, and persistence. It is useful for release planning and ownership mapping.
flowchart LR
subgraph Presentation Layer
pages[Next.js Pages\nPublic + Admin]
comps[UI Components\nStadium, Sports, Player, Shared]
end
subgraph Application Layer
routes[Route Handlers\n/api/*]
services[Domain Logic\nchat, discovery, qr]
end
subgraph Data and Integration Layer
prisma[Prisma Client]
neon[(Neon PostgreSQL)]
sql[Neon SQL Driver]
ext[External Services\nOpenAI, Cloudinary, Maps]
end
pages --> comps
pages --> routes
routes --> services
services --> prisma
services --> sql
prisma --> neon
sql --> neon
services --> ext
This map summarizes key product capabilities by user-facing functional areas. It helps align product and engineering scope without implementation-level complexity. Use it as a blueprint for feature planning.
mindmap
root((InStadium Web))
Discovery
Home
Search
Sports Catalog
Stadium Listing
Stadium Experience
Stadium Detail Page
Gallery
Timeline
Matches
Nearby Stadiums
Map Experience
Player Experience
Player Detail
Story and Timeline
Associated Stadiums
Engagement
Chat Assistance
Sport Booking Modal
Operations
Admin Dashboard
Data Utilities
This diagram explains how public routes, dynamic pages, and API routes are organized. It reflects the App Router structure and route-domain grouping currently used. Use this for onboarding and navigation across the codebase.
sequenceDiagram
autonumber
participant U as User
participant W as Web App
participant P as App Router Pages
participant A as Route Handlers
participant D as Neon DB
U->>W: Open home page and browse content
W->>P: Render public routes like /, /sports, /stadiums, /search
P->>A: Request dynamic or API-backed data
A->>D: Read stadium, sport, player, and QR data
D-->>A: Result set
A-->>P: JSON payload
P-->>W: Rendered page content
U->>W: Open /stadium/:id or /player/:id
W->>P: Resolve dynamic route
P->>A: Fetch detail data
A->>D: Query matching records
D-->>A: Detail record
A-->>P: Detail response
P-->>W: Detail page displayed
This diagram represents the platform as a single process and focuses on external exchanges. It shows what data enters the system and what results are delivered back. It intentionally avoids internal logic details.
flowchart LR
U[User] -->|browse, search, chat| P((InStadium Web Platform))
P -->|pages, recommendations, confirmations| U
P -->|query/read/write| D[(Operational Data Store)]
P -->|media fetch/store| M[Media Service]
P -->|prompt/reply| A[AI Service]
This Level 1 model decomposes major flows into domain processes and storage points. It is a practical reference for feature teams and operations alignment. It also helps identify process dependencies for reliability planning.
flowchart TB
U[Visitor/Admin]
P1((P1 Discover Stadiums and Sports))
P2((P2 View Detail Pages))
P3((P3 Resolve QR and Deep-Link))
P4((P4 AI Chat Interaction))
D1[(Stadium/Sport/Player Data)]
D2[(QR Mapping Records)]
E1[Cloudinary]
E2[OpenAI]
U --> P1
U --> P2
U --> P3
U --> P4
P1 <--> D1
P2 <--> D1
P3 <--> D2
P4 <--> E2
P2 <--> E1
This activity flow captures the most common public journey from landing page to detailed stadium insight. It includes search/filter loops and decision points for user refinement. Use it as a baseline for UX and conversion improvements.
flowchart TD
S([Start]) --> A[Open Home Page]
A --> B[Explore Sports and Featured Stadiums]
B --> C{Need specific result?}
C -->|Yes| D[Use Search or Sports Filter]
C -->|No| E[Continue browsing listings]
D --> F[Fetch filtered data]
E --> F
F --> G[Select stadium]
G --> H[Open Stadium Detail]
H --> I[Read timeline, matches, players, map]
I --> J([End])
This diagram shows the QR-based path from a scanned code to a resolved stadium context. It represents the core physical-to-digital transition in the platform. It can later be extended with validation and fallback branches.
flowchart TD
S([Start]) --> A[Visitor scans QR or opens code link]
A --> B[Open /qr/:code page]
B --> C[Call /api/qr/resolve]
C --> D[(QR Mapping Store)]
D --> E[Receive mapped stadium data]
E --> F[Redirect to stadium detail]
F --> G([End])
This sequence illustrates how a stadium detail page is resolved at runtime. It combines dynamic route resolution with API-driven data retrieval. This is one of the highest-traffic core paths.
sequenceDiagram
autonumber
participant U as User Browser
participant P as Stadium Page
participant R as /api/stadiums/[id]
participant DB as Neon DB
U->>P: Open /stadium/{id}
P->>R: Fetch stadium payload
R->>DB: Query stadium + sports + players
DB-->>R: Result set
R-->>P: JSON response
P-->>U: Rendered detail experience
This sequence describes QR code resolution used for deep-link stadium access. It validates mapping existence and returns mapped stadium metadata. This flow supports physical-to-digital transitions during venue visits.
sequenceDiagram
autonumber
participant U as User
participant W as Web QR Page
participant Q as /api/qr/resolve
participant DB as QR Mapping Store
U->>W: Open QR link or scan code
W->>Q: GET with code parameter
Q->>DB: Find mapping by qrCode
DB-->>Q: Mapping + stadium record
Q-->>W: Resolved payload
W-->>U: Redirect/display stadium context
This sequence shows how user prompts are processed by the chat route. When AI configuration is available, external model output is returned. Fallback behavior ensures graceful responses if keys are not configured.
sequenceDiagram
autonumber
participant U as User
participant C as Chat Widget
participant A as /api/chat
participant O as OpenAI
U->>C: Ask stadium question
C->>A: POST message + stadiumName
alt AI key available
A->>O: Create completion
O-->>A: Response text
A-->>C: Chat reply
else AI key missing
A-->>C: Fallback guidance reply
end
C-->>U: Display assistant response
This state model describes major user states during web usage. It separates anonymous browsing from admin interaction and utility flows. It is useful for access-control and navigation consistency checks.
stateDiagram-v2
[*] --> Landing
Landing --> Browsing
Browsing --> SearchMode
SearchMode --> Browsing
Browsing --> DetailView
DetailView --> Browsing
Browsing --> QRFlow
QRFlow --> DetailView
Browsing --> AdminLogin
AdminLogin --> AdminDashboard
AdminDashboard --> Browsing
Browsing --> [*]
This ER view maps the primary domain entities used by the application. It focuses on core business relationships and avoids low-level field specifics. Use it for model understanding and future migration planning.
erDiagram
SPORT }o--o{ STADIUM : played_at
SPORT ||--o{ PLAYER : categorizes
STADIUM }o--o{ PLAYER : appears_in
STADIUM ||--o{ QRMAPPING : has
SPORT {
string id
string name
string description
}
STADIUM {
string id
string name
string city
int capacity
}
PLAYER {
string id
string name
string country
string sportId
}
QRMAPPING {
string id
string qrCode
string stadiumId
datetime createdAt
}
This diagram represents a production-style logical deployment shape. It keeps cloud-provider details abstract while showing runtime dependencies. Use this view for environment planning and operational coordination.
flowchart TB
subgraph Client
browser[Web Browser]
end
subgraph App Hosting
nextapp[Next.js Runtime\nPages + API Routes]
end
subgraph Data and Services
neon[(Neon Postgres)]
media[Cloudinary]
llm[OpenAI]
end
browser --> nextapp
nextapp --> neon
nextapp --> media
nextapp --> llm
This map helps contributors quickly locate major areas of the codebase. It reflects current organization by route, component, API, and infrastructure modules. Use it during onboarding and feature scoping.
flowchart TB
root["InStadiumWeb"]
root --> app["src/app"]
root --> comp["src/components"]
root --> lib["src/lib"]
root --> prisma["prisma"]
root --> assets["public/images"]
root --> scripts["scripts"]
app --> pages["Public and Admin Pages"]
app --> api["API route handlers"]
comp --> stadiumComp["stadium components"]
comp --> sportsComp["sports components"]
comp --> playerComp["player components"]
lib --> dbLib["db and prisma clients"]
lib --> utilityLib["maps, cloudinary, api helpers"]
lib --> geoLib["geo distance utility"]
This section gives a production-grade summary without diving into deep implementation internals. It is enough for architecture review, release planning, and handoff readiness. Detailed contracts and runbooks can be added in the reserved section later.
- Framework: Next.js App Router
- Runtime: React + TypeScript
- Persistence: Neon PostgreSQL
- Data Access: Prisma Client and Neon serverless SQL driver
- Integrations: OpenAI chat, Cloudinary media services
- UI Additions:
BookingModalcomponent for sport-level event booking flows - Utilities:
geo.tslibrary for proximity-based nearby stadium distance calculation - Static Assets: Player image set added (
/public/images/players/) for key cricket, badminton, and tennis athletes - Data:
sports-data.tsandprisma/seed.tssignificantly expanded with richer sport and stadium content
- API handlers use dynamic route mode for fresh data paths where required
- Domain routes are grouped by bounded context (stadiums, sports, qr, chat, debug)
- Data retrieval mixes ORM and SQL approaches based on use case complexity
- Public browsing APIs are available for discovery-focused features
- Admin and debug surfaces are scoped to controlled use and environment conditions
- Secret-driven integrations (database and AI/media keys) are environment-configured
- Stateless API route design supports horizontally scalable deployments
- Structured route-level error responses provide operational clarity
- Data-centric operations can be monitored by route domain and environment logs
- Node.js 18+
- PostgreSQL connection string (Neon recommended)
npm install
npm run devnpm run build
npm run startDATABASE_URL=postgres://.../neondb?sslmode=require
OPENAI_API_KEY=optional-for-chat
CLOUDINARY_CLOUD_NAME=optional
CLOUDINARY_API_KEY=optional
CLOUDINARY_API_SECRET=optionalThese placeholders are intentionally left for phase-2 technical depth so this README stays clear but complete.
- Endpoint request and response schemas
- Error catalog and status-code matrix
- Auth and permission matrix by route
- Full ERD with constraints and indexing strategy
- Migration policy and backward compatibility approach
- Data retention and archival standards
- Threat model and trust boundaries
- Secret rotation and key-management standards
- Audit and monitoring controls
- SLO and error budget targets
- Capacity and load test strategy
- Incident response and rollback playbooks
- Branch and environment promotion strategy
- Quality gates and release checklist
- Rollback and hotfix policies
- High-level architecture: complete
- High-level data flows: complete
- Activity and sequence modeling: complete
- Technical baseline summary: complete
- Deep technical appendix content: intentionally reserved