Skip to content

Commit 0356e4b

Browse files
sreeosreeo
committed
add readme files for context management
1 parent 6fe7456 commit 0356e4b

File tree

3 files changed

+537
-2
lines changed

3 files changed

+537
-2
lines changed

‎ARCHITECTURE.md

+354
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,354 @@
1+
# Smart Postgres Application Architecture
2+
3+
## Application Flow Diagram
4+
5+
```mermaid
6+
graph TB
7+
subgraph "Frontend Layer"
8+
UI[User Interface]
9+
QI[Query Interface Component]
10+
DA[Database Analysis Component]
11+
SV[Schema Viewer Component]
12+
TT[Truncated Text Component]
13+
Theme[Theme Provider]
14+
15+
UI --> QI
16+
UI --> DA
17+
QI --> SV
18+
QI --> TT
19+
UI --> Theme
20+
end
21+
22+
subgraph "State Management"
23+
RS[React State]
24+
CTX[React Context]
25+
26+
QI --> RS
27+
DA --> RS
28+
UI --> CTX
29+
end
30+
31+
subgraph "API Layer"
32+
subgraph "Query Endpoints"
33+
GEN["API: /query/generate"]
34+
EXEC["API: /query/execute"]
35+
SCHEMA["API: /query/schema"]
36+
TEST["API: /query/test-connection"]
37+
end
38+
39+
QI --> GEN
40+
QI --> EXEC
41+
QI --> SCHEMA
42+
QI --> TEST
43+
end
44+
45+
subgraph "Service Layer"
46+
subgraph "Database Services"
47+
DBC[Database Client]
48+
DBInit[Database Initializer]
49+
SchemaService[Schema Service]
50+
QueryExecutor[Query Executor]
51+
end
52+
53+
subgraph "LLM Services"
54+
LLMClient[LLM Client]
55+
LLMInit[LLM Initializer]
56+
QueryGen[Query Generator]
57+
ErrorHandler[Error Handler]
58+
end
59+
60+
SCHEMA --> SchemaService
61+
GEN --> QueryGen
62+
EXEC --> QueryExecutor
63+
TEST --> DBC
64+
end
65+
66+
subgraph "External Services"
67+
PG[(PostgreSQL Database)]
68+
subgraph "LLM Providers"
69+
OR[OpenRouter API]
70+
OL[Ollama API]
71+
Custom[Custom OpenAI Compatible API]
72+
end
73+
74+
DBC --> PG
75+
SchemaService --> PG
76+
QueryExecutor --> PG
77+
78+
LLMClient --> OR
79+
LLMClient --> OL
80+
LLMClient --> Custom
81+
end
82+
83+
subgraph "Configuration Layer"
84+
Config[Configuration Manager]
85+
86+
subgraph "Database Config"
87+
DBCreds[Database Credentials]
88+
ConnPool[Connection Pool Settings]
89+
end
90+
91+
subgraph "LLM Config"
92+
LLMCreds[LLM API Credentials]
93+
Models[Available Models]
94+
Params[Model Parameters]
95+
end
96+
97+
Config --> DBCreds
98+
Config --> ConnPool
99+
Config --> LLMCreds
100+
Config --> Models
101+
Config --> Params
102+
end
103+
104+
subgraph "Data Flow"
105+
direction LR
106+
Input[User Input] --> |Natural Language| QueryGen
107+
QueryGen --> |SQL Query| QueryExecutor
108+
QueryExecutor --> |Results| QI
109+
SchemaService --> |Schema Info| QueryGen
110+
end
111+
112+
subgraph "Error Handling"
113+
EH[Error Handler]
114+
Validation[Input Validation]
115+
ErrorLogs[Error Logging]
116+
117+
EH --> ErrorLogs
118+
Validation --> EH
119+
QueryGen --> EH
120+
QueryExecutor --> EH
121+
end
122+
123+
subgraph "Security Layer"
124+
Auth[Authentication]
125+
San[Input Sanitization]
126+
Rate[Rate Limiting]
127+
128+
QI --> Auth
129+
QI --> San
130+
API --> Rate
131+
end
132+
133+
subgraph "Development Tools"
134+
Dev[Development Server]
135+
Build[Build Process]
136+
Lint[Linter & Formatter]
137+
Test[Testing Framework]
138+
end
139+
```
140+
141+
## Component Descriptions
142+
143+
### Frontend Layer
144+
- **User Interface**: Main application container
145+
- **Query Interface**: Handles natural language input and query results
146+
- **Database Analysis**: Provides database metrics and analysis
147+
- **Schema Viewer**: Displays database schema and relationships
148+
- **Theme Provider**: Manages application theming
149+
150+
### API Layer
151+
- **/api/query/generate**: Converts natural language to SQL
152+
- **/api/query/execute**: Executes SQL queries
153+
- **/api/query/schema**: Retrieves database schema
154+
- **/api/query/test-connection**: Tests database connectivity
155+
156+
### Service Layer
157+
- **Database Services**: Manages database connections and operations
158+
- **LLM Services**: Handles AI model interactions and query generation
159+
- **Schema Service**: Manages database schema information
160+
- **Query Executor**: Handles query execution and result pagination
161+
162+
### External Services
163+
- **PostgreSQL**: Target database system
164+
- **LLM Providers**:
165+
- OpenRouter (Claude, GPT-4)
166+
- Ollama (Local models)
167+
- Custom OpenAI-compatible endpoints
168+
169+
### Configuration Layer
170+
- **Database Config**: Connection and pool settings
171+
- **LLM Config**: API credentials and model parameters
172+
- **Application Config**: General application settings
173+
174+
### Security Layer
175+
- **Authentication**: User authentication
176+
- **Input Sanitization**: Query and input validation
177+
- **Rate Limiting**: API request limiting
178+
179+
### Development Tools
180+
- **Development Server**: Next.js development environment
181+
- **Build Process**: Production build pipeline
182+
- **Testing**: Unit and integration tests
183+
- **Linting**: Code quality tools
184+
185+
## Data Flow
186+
187+
1. User enters natural language query
188+
2. Query is validated and sanitized
189+
3. LLM service generates SQL query
190+
4. SQL query is executed against database
191+
5. Results are paginated and formatted
192+
6. UI displays results to user
193+
194+
## Error Handling
195+
196+
1. Input validation errors
197+
2. LLM generation errors
198+
3. Database execution errors
199+
4. Network and connection errors
200+
5. Rate limiting errors
201+
202+
## User Workflow Diagrams
203+
204+
### Database Connection and Query Workflow
205+
206+
```mermaid
207+
sequenceDiagram
208+
actor User
209+
participant UI as User Interface
210+
participant DB as Database Service
211+
participant LLM as LLM Service
212+
participant PG as PostgreSQL
213+
214+
%% Initial Setup
215+
User->>UI: Enter Database Credentials
216+
UI->>DB: Test Connection
217+
alt Connection Success
218+
DB->>PG: Verify Credentials
219+
PG-->>DB: Connection OK
220+
DB-->>UI: Connection Successful
221+
UI-->>User: Show Success & Continue
222+
else Connection Failed
223+
DB-->>UI: Connection Error
224+
UI-->>User: Show Error Details
225+
end
226+
227+
%% LLM Setup
228+
User->>UI: Enter LLM Configuration
229+
UI->>LLM: Initialize LLM Client
230+
alt LLM Setup Success
231+
LLM-->>UI: Ready for Queries
232+
UI-->>User: Show Query Interface
233+
else LLM Setup Failed
234+
LLM-->>UI: Configuration Error
235+
UI-->>User: Show Error & Retry Options
236+
end
237+
238+
%% Schema Loading
239+
UI->>DB: Request Schema
240+
DB->>PG: Fetch Schema Details
241+
PG-->>DB: Return Schema
242+
DB-->>UI: Display Schema
243+
244+
%% Query Process
245+
User->>UI: Enter Natural Language Query
246+
UI->>LLM: Generate SQL Query
247+
248+
alt Query Generation Success
249+
LLM-->>UI: Return SQL Query
250+
UI-->>User: Show Generated SQL
251+
252+
alt User Accepts Query
253+
User->>UI: Confirm Execute
254+
UI->>DB: Execute SQL
255+
DB->>PG: Run Query
256+
257+
alt Query Execution Success
258+
PG-->>DB: Return Results
259+
DB-->>UI: Format Results
260+
UI-->>User: Display Results
261+
262+
opt Export Results
263+
User->>UI: Request Export
264+
UI-->>User: Download CSV/JSON
265+
end
266+
267+
else Query Execution Failed
268+
PG-->>DB: Error Details
269+
DB-->>UI: Format Error
270+
UI-->>User: Show Error & Suggestions
271+
end
272+
273+
else User Modifies Query
274+
User->>UI: Edit Query
275+
UI->>LLM: Regenerate SQL
276+
end
277+
278+
else Query Generation Failed
279+
LLM-->>UI: Error Details
280+
UI-->>User: Show Error & Examples
281+
end
282+
283+
%% Analysis Features
284+
opt View Database Analysis
285+
User->>UI: Open Analysis View
286+
UI->>DB: Fetch Statistics
287+
DB->>PG: Get System Stats
288+
PG-->>DB: Return Stats
289+
DB-->>UI: Format Dashboard
290+
UI-->>User: Show Analysis
291+
end
292+
293+
%% Schema Exploration
294+
opt Explore Schema
295+
User->>UI: Open Schema View
296+
UI->>DB: Get Detailed Schema
297+
DB->>PG: Fetch Relations
298+
PG-->>DB: Return Details
299+
DB-->>UI: Format Schema View
300+
UI-->>User: Display Schema Browser
301+
end
302+
```
303+
304+
### Error Handling Workflow
305+
306+
```mermaid
307+
sequenceDiagram
308+
actor User
309+
participant UI as User Interface
310+
participant Val as Validator
311+
participant LLM as LLM Service
312+
participant DB as Database Service
313+
314+
%% Input Validation
315+
User->>UI: Submit Input
316+
UI->>Val: Validate Input
317+
alt Input Valid
318+
Val-->>UI: Validation OK
319+
UI->>LLM: Process Input
320+
else Input Invalid
321+
Val-->>UI: Validation Errors
322+
UI-->>User: Show Input Errors
323+
end
324+
325+
%% Rate Limiting
326+
alt Rate Limit Exceeded
327+
LLM-->>UI: Rate Limit Error
328+
UI-->>User: Show Cooldown Period
329+
end
330+
331+
%% Connection Errors
332+
alt Database Connection Lost
333+
DB-->>UI: Connection Error
334+
UI->>DB: Attempt Reconnect
335+
alt Reconnect Success
336+
DB-->>UI: Connection Restored
337+
UI-->>User: Resume Operation
338+
else Reconnect Failed
339+
UI-->>User: Show Connection Error
340+
end
341+
end
342+
343+
%% LLM Errors
344+
alt LLM Service Error
345+
LLM-->>UI: Service Error
346+
UI->>LLM: Retry Request
347+
alt Retry Success
348+
LLM-->>UI: Request Complete
349+
UI-->>User: Show Results
350+
else Retry Failed
351+
UI-->>User: Show Error & Alternatives
352+
end
353+
end
354+
```

0 commit comments

Comments
 (0)